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Using The Sun C Compiler 



This chapter describes how to compile C programs under the SunOS version of 
the UNIXt operating system running on Sun Microsystems’ Sun-3 and Sun-4 
(SPARC) workstations. 

If you are already familiar with using cc, (the UNIX C compiler), either on Sun 
workstations or on other UNIX systems, you can probably ignore or skim the rest 
of this chapter without regretting it later. 

If you need to learn about programming in C, or about SunOS programming 
tools, you should refer to one or more of the introductory books available that 
address the topic. 



1.1. Basics — Compiling This section shows how to compile and run a minimal C program. Consider this 



and Running C 
Programs 


C program that just displays a message and exits: 






r 

main U 

\ V : . ... 

print f ( ,f Real Programmers ; Hack : C ! \n" ) ; : 






exit (0) ; 











Using your preferred text editor, save the text of this program in a file called 
hackers . c. After you have saved the file, compile it with the cc command: 



tutorial% cc hackers. c 

tutorial% 





cc works silently unless there are errors in the program. In this case, there are 
no errors, and cc compiles the program and saves an executable version of it in a 
file named a .out. 



f UNIX is a registered trademark of AT&T. 




sun 

microsystems 



Revision A of 27 March, 1990 





2 C Programmer’s Guide 



When you want to run the program, type the name of the executable file: 



r 


■\ 


tutorial% a. out 




Real Programmers Hack C! 




tutorial% 




v 


/ 



Note that the program’s last line was an exit ( ) statement. If run interactively 
from a shell, either with or without the final line, this program will behave as 
expected: 



. 

tutorial% a. out 

Real Programmers Hack C! 

tutorial% 

V ) 



However, if the same program (minus exit ( ) ) is executed in an environment 
which examines the program’s exit status, unexpected results may occur. In par- 
ticular, if the program is executed from a Makefile, an unexpected error code 
may be reported: 



f > 
tutorial% cat Makefile 

example : example . c 

cc example . c -o example 
example 

tutorial% make 

cc example. c -o example 

example 

main returns value which is NOT ignored 
*** Error code 40 

make: Fatal error: Command failed for target 'example' 
tutorial% 

s 



This strange message may be explained by noting that make examines the exit 
status of each program that it invokes, where the program’s exit status is the 
value returned by main ( ) or passed to exit ( ) . If main ( ) does not return a 
value or call exit ( ) , the exit status is undefined and the program is in error. 
This error may be detected by running system V lint on the suspect program: 



/ \ 

tutorial% /usr/5bin/lint example. c 

example . c 

(4) warning: main() returns random value to invocation environment 
< j 



This program may be corrected by adding a return statement or a call to 
exit () . 
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1.2. C Compiler 



1.3. cc Options 
-a Option 



-align _block_ Option 



More generally, if a function f ( ) is declared with a result type, but ends without 
returning a result, and the (undefined) result of f ( ) is used in an expression con- 
taining a call to f ( ) , then the program is in error. 

Some earlier versions of the compiler permitted programs that did not incor- 
porate either a terminating exit ( ) or return function. 



This section describes the compiler options supported by Sun Microsystems’ C 
compiler. Later sections cover specific dependencies and features of Sun C 
under SunOS. 



. 

cc [ options ] filename [ libraries ] . . . 

V J 



cc translates programs written in C into executable load modules, (or into relo- 
catable binary programs for later linking with ld(l)), and optionally links (or 
binds) the result with object files generated by cc or other language processors. 

cc accepts a list of C source files and various object files contained in the list of 
files specified by filename.... The resulting executable is placed in the file a.out, 
unless the (-o) option is specified (see below). 

cc lets you compile and link any combination of the following: 

□ C source files (with a . c suffix) 

□ C preprocessed source files with a . i suffix 

□ SunOS system object-code files with . o suffixes 

□ Assembler source files with . s suffixes 

After successfully linking, cc places the product of linking those files in the file 
a . out, or in the file specified by the -o option. Note that, unless otherwise 
specified, options may follow the the filename, as in cc file.c -o file. 



This option directs cc to insert code to count how many times each basic block 
in a program is executed. This creates a . d file for every . c file compiled that 
accumulates execution data for its corresponding source file. On the Sun-3, 
Sun-4, and SPARCStation, you can then run tcov(l) on the source files to gen- 
erate statistics about the program. 

Since this option entails some optimization, it is incompatible with -g. 

This option directs cc to page-align the uninitialized global uninitialized data 
symbol block, which is equivalent to a FORTRAN common block . This 
increases its size to a whole number of pages, and places its first byte at the 
beginning of a page. Multiple -align options may be given. 
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-B binding Option 

-c Option 

-C Option 
-dalign Option 

-dry run Option 
-Dname[—def\ Option 

-E Option 

Floating-Point Options 



This option specifies whether bindings of libraries for linking are static or 
dynamic, indicating whether libraries are non-shared or shared, respectively. 

This option directs cc to suppress linking with ld(l) and produce a . o file for 
each source file. You can explicitly name a single object file with the -o option. 

This option prevents the C preprocessor, cpp(l), from removing comments. 

This option generates double load/store instructions whenever possible for 
improved performance. Assumes that all double typed data are double aligned, 
and should not be used when correct alignment is not assured. 

Sun-4 and SPARCstation only. 

This option directs cc to show but not execute the commands constructed by the 
compilation driver. 

This option defines a symbol name to the C preprocessor cpp(l). This is 
equivalent to a #def ine directive at the beginning of the source. If you don’t 
use =def, name is defined as ‘1’. Multiple -D options may be given. 

This option runs the source file through cpp only. It sends the output to either 
stdout, or to a file named with the -o option (which must end with . i) and 
includes the cpp line numbering information. (See also, the -P option.) 

Sun supports several ways to perform floating-point calculations, both in 
hardware and software. The floating-point point options provided by cc permit 
you to choose the way that gives you the best performance and portability for 
your programs. 

The following floating-point code generation option can be used on Sun-3, Sun-4 
and SPARC systems: 

-f single This option directs cc to use single-precision arithmetic in com- 
putations involving only float expressions — that is, do not 
convert everything to double, which is the default. Note that 
floating-point parameters are still converted to double precision, 
and functions returning values can still return double-precision 
values. 

Although this is not traditional C practice, some programs run 
much faster using this option. Be aware that some significance can 
be lost due to lower-precision intermediate values. 

The floating-point code generation options useable on Sun-3s can be any of the 

This option directs cc to generate in-line code for the Motorola 
MC6888 1 floating-point coprocessor (Sun-3 systems only). 

This option directs cc to generate in-line code for the Sun 
Floating-Point Accelerator (Sun-3 systems only). 
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-f 68881 

-f fpa 



t^sun 

V microsystems 





Chapter 1 — Using The Sun C Compiler 5 



-g Option 

-go Option 

-help Option 

-Ipathname Option 



- J Option 

-1 library Option 

-L dir Option 
-M Option 



-f sof t This option directs cc to generate software floating-point calls 

(this is the default for all Sun-3 workstations). 



-f st or e This option insures that expressions allocated to extended preci- 

sion registers are rounded to storage precision whenever an 
assignment occurs in the source code. 

Only effective if-f68881 is specified (Sun-3 systems only). 

-f switch This directs cc to generate runtime-switched floating-point calls. 

The compiled object code is linked at runtime to routines that sup- 
port one of the above types of floating-point code. This option is 
not recommended. 



This option produces additional symbol table information for dbx(l) and 
dbxtool{ 1), and passes the -lg flag to ld(l) so as to include the g library, 
/usr/lib/libg . a. This option suppresses the -0 and -R options. 

This option produces additional symbol table information for adb(l). When this 
option is given, the -0 and -R options are suppressed. 

This option displays information about cc . 

This option adds pathname to the list of directories that are searched for 
#include files with relative filenames (those not beginning with slash/). 

The preprocessor first searches for # include files in the directory containing 
sourcefile, then in directories named with - I options (if any), and finally, in 
/usr/include. Programs that use systems calls, for example, would need to 
use the file types . h as one of their tinclude files, types . h contains 
many type definitions used by common system calls. 

This option generates 32-bit offsets in swit ch() statement branches (Sun-3 sys- 
tems only). 

This option directs Id to link with object library library. The ordering of 
libraries in the compile line is important, as symbols are resolved from left to 
right. 

Note This option must follow the sourcefile arguments. 

This option adds dir to the list of directories containing object-library routines 
(for linking with Id). 

This option runs only the macro preprocessor on the named C programs, request- 
ing that it generate makefile dependencies and send the result to the standard out- 
put (see malce(l) for details about makefiles and dependencies). 
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-misalign Option 
-o outputfde Option 



-0 [level] 



-p Option 



-P Option 



-pg Option 



-pic Option 



-PIC Option 



This option generates code to allow loading and storage of misaligned data 
(Sun-4 and SPARC systems only). 

This option names the output file outputfde. outputfde must have the appropriate 
suffix for the type of file to be produced by the compilation, outputfde cannot be 
the same as sourcefde since cc will not overwrite the source file. 

This option directs cc to optimize the object code. It is ignored when either -g, 
-go, or -a are used, level can be one of the following: 

1 Do postpass assembly-level optimization only. 

2 Do global optimization before code generation, including loop optimiza- 
tions, common subexpression elimination, copy propagation, and automatic 
register allocation. -02 does not optimize references to or definitions of 
external or indirect variables. 

3 Same as -02, but optimize uses and definitions of external variables. -03 
does not trace the effects of pointer assignments. Neither L-03 nor -04 
should be used when compiling either device drivers, or programs that 
modify external variables from within signal handlers. 

4 Same as -03, but traces the effects of pointer assignments. 

Note If you use -0 without specifying the level, it is equivalent to using -02. 

This option prepares the object code to collect data for profiling with prof (1). 

-p invokes a run-time recording mechanism that produces a mon.out file at nor- 
mal termination. 

This option runs the source file through cpp(l), the C preprocessor, only. It then 
puts the output in a file with a . i suffix. Does not include cpp-type line number 
information in the output. 

This option prepares the object code to collect data for profiling with gprof (1). 
It invokes a run-time recording mechanism that produces a gmon . out file at 
normal termination. 

This option produces position-independent code. Each reference to a global 
datum is generated as a dereference of a pointer in the global offset table. Each 
function call is generated in pc-relative addressing mode through a procedure 
linkage table. The size of the global offset table is limited to 64K on Sun-3 sys- 
tems, or to 8K on SPARC stations. 

This option is similar to -pic, but lets the global offset table span the range of 
32-bit addresses in those rare cases where there are too many global data objects 
for -pic. 
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-pipe Option This option directs cc to use pipes, rather than intermediate files, between com- 

pilation stages. (Very CPU-intensive.) 

-Qoption prog opt Option This option passes the option opt to the compiler phase prog. The option must 

be appropriate to that program and may begin with a minus sign, prog can be 
one of: as(l), cpp(l), inline, orld(l). 

-Qpath pathname Option This option inserts a directory pathname into the search path used to locate com- 

piler components. This path will also be searched first for certain relocatable 
object files that are implicitly referenced by the compiler driver, for example 
* c r t * . o and bb_l i nk . o . This lets you choose whether or not to use default 
versions of programs invoked during compilation. 

-Qproduce sourcetype This option causes cc to produce source code of the type sourcetype. sourcetype 

Option can be one of the following: 

. c C source (from bb_count). 

. i Preprocessed C source from cpp. 

. o Object file from as. 

. s Assembler source (from ccom, inline(l), or c2. 



-R Option This option directs cc to merge the data segment with the text segment for 

as(l). Data initialized in the object file produced by this compilation is read- 
only, and (unless linked with Id -N) is shared between processes. This option 
is ignored when either -g or -go are used. 

This option directs cc to produce an assembly source file but not to assemble the 
program. 

This option generates extra symbol table information for the Sun Source Code 
Browser. This is an unbundled product that will be released based on 4.1. 

This option compiles object files for the specified processor architecture. Unless 
used in conjunction with one of the Sun Cross-Compilers, correct programs can 
be generated only for the architecture of the host on which the compilation is per- 
formed. tar get arch can be one of: 

-sun2 Produce object files for a Sun-2 system. 

-sun3 Produce object files for a Sun-3 system. 

-sun4 Produce object files for a Sun-4 and SPARC systems. 

-temp= dir Option This option sets the directory to contain temporary files generated during the 

compilation process to be dir. 



-S Option 
-sb Option 
target_arch Option 
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-time Option 

-VSname Option 

-w Option 

1.4. Environment 

FLOAT OPTION 



This option directs cc to report execution times for the various compilation 
passes. 

This option removes any initial definition of the cpp symbol name. This option 
is the inverse of the -D option. Multiple -U options may be given. 

This option directs cc to not print warnings. 



(Sun-3, Sun-4, and SPARC systems only.) When no floating-point option is 
specified, the compiler uses the value of this environment variable (if set). 
Recognized values are: f 68881, ffpa, f sky, f switch and f soft. 
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Accessing a Program’s Environment 



This chapter discusses two basic topics: 

□ How to get the arguments from the command line used to run a program. 

□ How to access environment variables. 

2.1. Basics — Accessing Assuming that you have written a C program, you might like to be able to get 

Command Line information from the command line when the user starts up the program. 

Arguments Although many SunOS system programs are run as filters — they obtain input 

from the standard input and send output to the standard output, sometimes you 
might like to be able to specify alternative files to operate upon, or to specify 
options on the command line to control the program’s behavior. 

When a C program is run as a command, the arguments on the command line are 
made available to the program’s main ( ) function as its first two arguments, an 
argument count argc and an array argv of pointers to character strings that 
contain the arguments. By convention, argv [ 0 ] is the command name itself, 
so argc is always greater than 0. Since argv is not NULL-terminated, you 
must use argc when traversing it. 

The following program illustrates the mechanism: it simply echoes its arguments 
back to the terminal — this is essentially the echo command. 



# include <stdio.h> 

main ( argc,- • ' ' argv ) / * e ch o : ; • ll$;!!li;|lllij: 

int argc; 




\ 


char *argv[] ; 

ill 

int arg_count; 

for (arg_count = 1; arg_count < argc; arg_count-f+) 






printf (”%s%c ,, f argv[arg_count J , (arg_count<argc-l) ? ' : 

exit (0) ; 

1 


: '\n')t 









argv is a pointer to an array whose elements are pointers to arrays of characters; 
each is terminated by \ 0, so they can be treated as strings. The program starts by 
printing argv [1] and loops until it has printed argv [ argc-1 ] . 




sun 

microsystems 



9 



Revision A of 27 March, 1990 





10 C Programmer’s Guide 



2.2. Basics — Accessing 
Environment 
Variables 



The argument count and the arguments are parameters to main, so if you want to 
keep them around for other routines to use, you must copy them to external vari- 
ables. 

The next topic is how to obtain values from a running program’s environment. 

You can ‘tailor’ your SunOS system environment by setting environment vari- 
ables, and these environment variables are accessible from a program. 

When a C program is started, three arguments are passed to its main function. 

In addition to argc and argv as described above, there is an array (named 
envp) of pointers to the character strings that comprise the environment. 

Each environment variable is a null-terminated character string of the form name 
= value that can be manipulated like any other character string. ( envp itself is 
also null-terminated.) 

Here is a short program to display all the environment variables: 



♦include <stdio.h> 

main (argc, argv, envp) 
int argc; 
char *argv(J; 

char *envp(]; 



int env_count = 0; . 

’r while (envp [env_count] != NULL) : { 
printf ("%s\n”, envp [env_count ] ) ; 

env^ountif 

1 111 111 lllll !!!||||||||| 

> exit (0 ) ; 



If you save the above text as environ . c, you can compile and run it as fol- 
lows: 



_ 

tutorial% cc environ. c 
tutorial% a. out 
HOME=/usr /henry 
SHELL=/bin/csh 

PATH=/usr/doctools/bin : /usr/local : . : /usr/ucb : /bin: /uar/bin 

TERM=sun 

USER=henry 

EXINIT=set noai wrapmargin=16 para=IPLPPPQPLSLEDSDETSTEKSKEPSPEEQENLIpplpipbp 

WINDOW_PARENT=/dev/winO 

WINDOW_ME=/dev/win8 

WINDOW_GFX= /de v/ win 8 

tutorial% 

s J 
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Accessing Environment 
Variable Using getenv() 



While environ . c is somewhat useful, parsing the name = value pairs is rather 
tedious, so there is a C library function called getenv ( ) whose purpose is to 
get values from the environment Here is the interface definition for getenv ( ) : 



char *getenv (name) 

char *name; 



Now we can compose a program that displays the value of a variable supplied as 
an argument on its command line: 



/* getenv () .c — obtain specified variable from environment */ 

#include <stdio.h> 

main (argc, argv) 

char *getenv (); 

int argc; 

char *argv [ ] ; 



char * variable/ 

/* Check . any argument supplied. */ 

if. (argc < 2) { : 

printf ("Usage : %s name\n' # , argv [03 < 

. exit (1) ; 

/* ■' Search • for : the variable. i- */ • 
if ((variable - getenv (argv [ 1] ) ) HULL) 
printf ("%s:i no variable. %s\n", . argv 10] j : : . ar^y fil 
else 

printf ("%s = %s\n # V argvfl], variable); 
exit ( 0) ; 



After compiling this program, you can use it like this: 



tutorial% a. out PATH 

PATH = /usr/doctools/bin : /usr/local : 

tutorial% a. out nonesuch 

a. out: no variable nonesuch 

tutorial% a. out 

Usage: a . out name 

tutorial% 



: /usr/ucb : /bin : /usr/bin 
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j 



3 



Processes 



The following section describes how to execute one program from within 
another. This makes it possible to use existing programs rather than always hav- 
ing to write new ones. 

3.1. The system () The easiest way to execute a program from another is to use the standard library 

Function routine system ( ) . system ( ) takes one argument, a command string exactly 

as typed at the terminal (except for the newline at the end) and executes it — for 
instance, to timestamp the output of a program, and returns a status word. 




The in- memory formatting capabilities of sprintf ( ) are useful if you must 
build the command string from pieces. 

3.2. Low-Level Process If you’re not using the standard library, or if you need finer control over what 

Creation — execl ( ) happens, you will have to construct calls to other programs using more primitive 

and execv ( ) routines that the standard library’s system () routine is based on 1 . 

The most basic operation is to execute another program without returning, by 
using the routine execl () . For example, you can display the date as the last 
action of a running program: 



execl ( "/bin/date", "date”, NULL) ; 

^ ) 



1 system ( ) uses fbin/sh (the Bourne Shell) to execute the command string, so syntax specific to the C- 
Shell will not work. 
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The arguments that you pass to execl ( ) are: 

1. The filename of the command that you want executed; you have to know 
where it is found in the file system. 

2 The second argument is conventionally the program name (that is, the last 
component of the file name), but this is seldom used except as a placeholder. 

3. If the command takes arguments, they are strung out in order, as a comma- 
separated list, after the program name (or its position). 

4. Following the arguments, the end of the list is marked by a NULL argument. 

The execl ( ) call overlays the existing program with the new one, runs that, 
then exits. There is no return to the original program. 

More commonly, a program falls into two or more phases that communicate only 
through temporary files. Here it is natural to start the second pass simply by an 
execl ( ) call from the first. 

The one exception to the rule that the original program never gets control back 
occurs when there is an error in performing the execl ( ) call itself, for example 
if the file can’t be found or is not executable. If you don’t know where date ( ) 
is located, you might try 



. 

execl ("/bin /date", "date", NULL) ; 
execl ("/usr/bin/date", "date", NULL); 
fprintf (stderr, "Someone stole r date'\n"); 



A variant of execl ( ) called execv ( ) is useful when you don’t know in 
advance how many arguments there are going to be. The call is 



execv (filename, argp); 



where argp is an array of pointers to the arguments; the last pointer in the array 
must be NULL so execv ( ) can tell where die list ends. As with execl ( ) , 
filename is the file in which the program is found, and argp [ 0 ] is the name 
of the program. (This arrangement is identical to the argv array for program 
arguments.) 

Neither of these routines provides the niceties of normal command execution. 
There is no automatic search of multiple directories — you have to know pre- 
cisely where the command is located. Nor do you get the expansion of metachar- 
acters like <, >, *, ? and [] in the argument list. If you want these, use 
execl ( ) to invoke a shell sh(l), which then does all the work. Construct a 
string commandline that contains the complete command as it would have 
been typed at the terminal, then call 
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execl ("/bin/sh", "sh", c" , commandline, NULL); 

< j 



The shell is assumed to be at a fixed place, /bin / sh. Its argument -c says to 
treat the next argument as a whole command line, so it does just what you want. 
The only problem is in constructing the right information in commandline. 

3.3. Process Control — So far what we’ve talked about isn’t really all that useful by itself. Next we show 

fork ( ) and wait ( ) how to regain control after running a program with execl ( ) or execv ( ) . 

Since these routines simply overlay the new program on the old one, to save the 
old one requires that it first be split into two copies; one of these can be overlaid, 
while the other waits for the new, overlaying program to finish. The splitting is 
done by a routine called f ork ( ) : 



\ 

proc_id = fork ( ) ; 





This call splits the program into two copies, both of which continue to run. The 
only difference between the two is the value of proc_id, the process id. In one 
of these processes (the child), proc_id is zero. In the other (the parent), 
proc_id is nonzero; it is the process number of the child. Thus the basic way 
to call, and return from, another program is 





\ 


if (fork ( ) == 0) 




execl ("/bin/sh", "sh" , 


"“C", cmd, NULL); /* in child */ 


v 


J 



And in fact, except for handling errors, this is sufficient. The fork ( ) makes 
two copies of the program. In the child, the value returned by fork ( ) is zero, 
so it calls execl () which does the command and then dies. In the parent, 
fork ( ) returns nonzero, so it skips the execl ( ) . If there is an error, fork ( ) 
returns -1. 

More often, the parent wants to wait for the child to terminate before continuing 
itself. This can be done with the function wait ( } : 



r 


> 


int status; 




if (fork ( ) ===== 0) 




execl (...); 




wait (& status) ; 




V 


J 



This still doesn’t handle any abnormal conditions, such as a failure of the 
execl ( ) or fork ( ) , or the possibility that there might be more than one child 
running simultaneously. The wait ( ) returns the process id of the terminated 
child, in case you want to check it against the value returned by f ork ( ) . 
Finally, this fragment doesn’t deal with any unusual behavior on the part of the 
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child (which is reported in status). Still, these three lines are the heart of the 
standard library’s system ( ) routine, which we’ll show in a moment. 

The status returned by wait ( ) encodes in its low-order eight bits the 
system’s idea of the child’s termination status; it is 0 for normal termination and 
nonzero to indicate various kinds of problems. The next higher eight bits are 
taken from the argument of the call to exit ( ) which caused a normal termina- 
tion of the child process. It is good coding practice for all programs to return 
meaningful exit status. (A program that does not explicitly call exit ( ) does 
not automatically return a 0 status.) 

When a program is called by the shell, the three file descriptors 0, 1, and 2 are set 
up to point to the right files (see Appendix A.1), and all other possible file 
descriptors are available for use. When this program calls another one, correct 
etiquette suggests making sure the same conditions hold. Neither fork ( ) nor 
exec affects open files in any way. If the parent is buffering output that must 
come out before output from the child, the parent must flush its buffers before the 
execl ( ) . Conversely, if a caller buffers an input stream, the called program 
will lose any information that has been read by the caller. 

3.4. Pipes A pipe is an I/O channel intended for use between two cooperating processes: 

one process writes into the pipe, while the other process reads from the pipe. The 
system looks after buffering the data and synchronizing the two processes. Most 
pipes are created by the shell, as in 



f 




\ 


tutorial 1 ! Is 


pr 




v 




J 



which connects the standard output of Is to the standard input of pr. Some- 
times, however, it is most convenient for a process to set up its own plumbing; in 
this section, we illustrate how the pipe connection is established and used. 

The system call pipe ( ) creates a pipe. Since a pipe is used for both reading 
and writing, two file descriptors are returned; the actual usage is like this: 



r 


A 


int fd[2] ; 




stat = pipe (fd) ; 




if (stat == -1) 




/* there was an error ... */ 




v 


/ 



f d is an array of two file descriptors, where f d [ 0 ] is the read side of the pipe 
and f d [ 1 ] is for writing. These may be used in read, write ( ) and 
close ( ) calls just like any other file descriptors. 

If a process reads a pipe which is empty, it waits until data arrives; if a process 
writes into a pipe which is full, it waits until the pipe empties somewhat. If the 
write side of the pipe is closed, a subsequent read will encounter end of file. 
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To illustrate the use of pipes in a realistic setting, let us write a function called 
popen ( cmd, mode ) , which creates a process cmd (just as system ( ) does), 
and returns a file descriptor that will either read to or write from that process, 
according to mode. That is, the call 

\ 

fout = popen ("pr", WRITE); 

V / 



creates a process that executes the pr command; subsequent write ( ) calls 
using the file descriptor fout will send their data to that process through the 
pipe. 



popen ( ) first creates the pipe with a pipe ( ) system call; it then fork ( ) ’s to 
create two copies of itself. The child decides whether it is supposed to read or 
write, closes the other side of the pipe, then calls the shell (via execl ( ) ) to run 
the desired process. The parent likewise closes die end of the pipe it does not 
use. These closes are necessary to make end-of-file tests work properly. For 
example, if a child that intends to read fails to close the write end of the pipe, it 
will never see the end of the pipe file, just because there is one writer potentially 
active. 



finclude <stdio.h> 



#def ine READ 
# define WRITE 
tdefine tst (a, 
static int 



0 

1 

b) (mode 

popen_pid; 



READ ? (b) : (a) ) 



pope n ( cmd , mode ) 
char *cmd; 

int mode ; 

{ 

int p [ 2 ] ; 

if (pipe (p) < 0) 
return (NULL) ; 

if ( (popen_jpid = fork ( ) ) -- 0) { 

close (tst (p [WRITE ] , p [READ] ) ) ; 
close (tst (0, 1)); 
dup (tst (p [READ] , p [WRITE] ) ) ; 
close (tst (p [READ] , p [WRITE] ) ) ; 
execl ("/bin/sh" , "sh”, "-c", cmd, 0); 

_exit(l); /* disaster has occurred if we get here */ 

} 

if (popen__pid == -1) 
return (NULL) ; 

close (tst (p [READ] , p[WRITEJ)); 

return (tst (p [WRITE] , p[READ])); 

} 



The sequence of close ( ) ’s in the child is a bit tricky. Suppose that the task is 
to create a child process that will read data from the parent. Then the first 
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close ( ) closes the write side of the pipe, leaving the read side open. The lines 



r 


A 


close (tst (0, 1) ) ; 




dup (tst (p [READ] , p [WRITE])); 






_ - -J 



are the conventional way to associate the pipe descriptor with the standard input 
of the child. The close ( ) closes file descriptor 0, that is, the standard input, 
dup () is a system call that returns a duplicate of an already open file descriptor. 
File descriptors are assigned in increasing order and the first available one is 
returned, so the effect of the dup ( ) is to copy the file descriptor for the pipe 
(read side) to file descriptor 0; thus the read side of the pipe becomes the standard 
input 2 . Finally, the old read side of the pipe is closed. 

A similar sequence of operations takes place when the child process is supposed 
to write to the parent instead of reading. You may find it a useful exercise to step 
through that case. 

The job is not quite done, for we still need a function pclose ( ) to close the 
pipe created by popen ( ) . The main reason for using a separate function rather 
than close ( ) is that it is desirable to wait for the termination of the child pro- 
cess. First, the return value from pclose ( ) indicates whether the process suc- 
ceeded. Equally important when a process creates several children is that only a 
bounded number of unwaited-for children can exist, even if some of them have 

terminated; performing the wait ( ) lays the child to rest. Thus: 
— 

♦include <signal.h> 

pclose (fd) /* close pipe fd */ 

int fd; 

{ 

register r, (*hstat) ( ), (*istat) ( ), (*qstat) ( ); 
int status; 

extern int popen_pid; 

close (fd) ; 

istat = signal (SIGINT, SIG_IGN) ; 
qstat = signal (SIGQUIT, SIG_IGN) ; 
hstat = signal (SIGHUP, SIG_IGN) ; 

while ((r = wait (Sstatus) ) != popen_pid && r != -1); 

if (r == -1) 

status = -1; 
signal (SIGINT, istat); 
signal (SIGQUIT, qstat); 
signal (SIGHUP, hstat) ; 
return (status) ; 




2 Yes, this is a bit tricky, but it’s a 



standard idiom. 
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The calls to signal ( ) make sure that no interrupts, etc., interfere with the 
waiting process; this is the topic of the next section. 

The routine as written has the limitation that only one pipe may be open at a 
time, because of the single shared variable popen_pid; it really should be an 
array indexed by file descriptor. A popen ( ) function, with slightly different 
arguments and return value, is available as part of the standard I/O library dis- 
cussed later. As currently written, it shares the same limitation. 
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Signals — Interrupts and All That 



This chapter is concerned with how to deal gracefully with signals from the out- 
side world (like interrupts) and with program faults. Since there’s nothing very 
useful that can be done from within a C program about program faults, which 
arise mainly from illegal memory references or from execution of peculiar 
instructions, we’ll discuss only the outside world signals: interrupt and quit, 
which are generated from the keyboard, hangup, caused by hanging up the phone 
on dialup lines, and terminate, generated by the kill command. When one of 
these events occurs, the signal is sent to all processes which were started by the 
corresponding user — the signal terminates the process unless other arrange- 
ments have been made. In the quit case, a core image file is written for debug- 
ging purposes. 

signal ( ) is the routine which alters the default action, signal ( ) has two 
arguments: the first specifies the signal to be processed, and the second argument 
specifies what to do with that signal. The first argument is just a numeric code, 
but the second is either a function, or a somewhat strange code that requests that 
the signal either be ignored or that it be given the default action. The include file 
signal . h gives names for the various arguments, and should always be 
included when signals are used. Thus 



r 




♦include <signal.h> 




signal (SIGINT, SIG_IGN) ; 




V 


J 


means that interrupts are to be ignored, while 






signal (SIGINT, SIG_DFL) ; 


I 


L _ ... _ 





restores the default action of process termination. In all cases, signal ( ) 
returns the previous value of the signal. The second argument to signal ( ) 
may instead be the name of a function (which must be declared explicitly if the 
compiler hasn’t seen it already). In this case, the named routine is called when 
the signal occurs. Most commonly this facility is used so that the program can 
clean up unfinished business before terminating, for example to delete a tem- 
porary file: 
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♦include <signal.h> 
main( ) 

int onintr ( ) ; 

>/,' .' file *temp>file, • *fopen () ; ■ 

if (signal (SlGINT f $IG_IGN) != $IG_IGN) 
signal (SIGINT, onintr); 

/* Process . . . */ 

exit (0 ) ; 

onintr ( ) 

■K V > , .v i',-, ^ 

unlink (tempfile) ; 

. exit(l) ; 

; ; ^ J 



Why the test and the double call to signal ( ) ? Recall that signals, like inter- 
rupts, are sent to all processes started from a particular user. Accordingly, when 
a program is to be run non-interactively (started with &), the shell turns off inter- 
rupts for it so it won’t be stopped by interrupts intended for foreground 
processes. If this program began by announcing that all interrupts were to be 
sent to the onintr ( ) routine regardless, that would undo the shell’s effort to 
protect it when run in the background. 

The solution, shown above, is to test the state of interrupt handling, and to con- 
tinue to ignore interrupts if they are already being ignored. The code as written 
depends on the fact that signal ( ) returns the previous state of a particular sig- 
nal. If signals were already being ignored, the process should continue to ignore 
them; otherwise, they should be caught. 

A more sophisticated program may wish to intercept an interrupt and interpret it 
as a request to stop what it is doing and return to its own command processing 
loop. Think of a text editor — interrupting a long display should not terminate 
the edit session and lose the work already done. The oudine of the code for this 
case may be written like this: 
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♦include <signal.h> 

♦include <set jmp.h> 
jmp_buf sjbuf; 

onintr ( ) 

{ 

printf ("\nlnterrupt\n") ; 

long jmp (sjbuf ) ; /* return to saved state */ 

} 

main( ) 

int (*istat) ( ), onintr ( ); 

istat *= signal (SXGINT, SIG_IGN) ; /* save old status */ 

set jmp (sjbuf ) ; /* save current stack position */ 

if (istat != SIG_IGN) 

signal (SIGINT, onintr) ; 

/* main processing loop */ 

} 

v aaa : Ml jw i : ■ ■■ ■■ ■ : ' : : : 



The include file set jmp . h declares the type jmp_buf — an object in which a 
process’s state can be saved, sjbuf is such an object. The set jmp ( ) routine 
then saves the state. When an interrupt occurs the onintr ( ) routine is called, 
which can display a message, set flags, or whatever, long jmp ( ) takes as argu- 
ment an object set by set jump ( ) , and restores control to the location following 
the call to set jump ( ) , so control (and the stack level) will pop back to the 
place in the main routine where the signal is set up and the main loop entered. 
Notice, by the way, that the signal gets set again after an interrupt occurs. 

Some programs that want to detect signals simply can’t be stopped at an arbitraiy 
point, for example in the middle of updating a linked list. If the routine called 
when a signal occurs sets a flag and then returns instead of calling exit ( ) or 
long jmp ( ) , execution continues at the exact point it was interrupted. The 
interrupt flag can then be tested later. 

There is one difficulty associated with this approach. Suppose the program is 
reading the standard input when the interrupt is sent. The specified routine is 
duly called; it sets its flag and returns. If it were really true, as we said above, 
that ‘execution resumes at the exact point it was interrupted,’ the program would 
continue reading stdin until the user typed another line. This behavior might 
well be confusing, since the user might not know that the program is reading; he 
presumably would prefer to have the signal take effect instantly. The method 
chosen to resolve this difficulty is to terminate the read when execution resumes 
after the signal, returning an error code which indicates what happened. 

Thus programs which catch and resume execution after signals should be 
prepared for ‘errors’ which are caused by interrupted system calls. 




Revision A of 27 March, 1990 





24 C Programmer’s Guide 



The ones to watch out for are read ( ) , wait ( ) , and pause ( ) . A program 
whose onintr ( ) routine just sets int f lag, resets the interrupt signal, and 
returns, should usually include code like the following when it reads the standard 
input: 



r 




if (getcharO — EOF) 




if (intflag) 




/ * EOF caused by interrupt */ 




else 




/* true end-of-file */ 




v 





A final subtlety to keep in mind becomes important when catching signals is 
combined with executing other programs. Suppose a program catches interrupts, 
and also includes a method (like *!’ in ex and vi) whereby other programs can be 
executed. Then the code should look something like this: 



r 

if (fork ( ) == 
execl (...) 


0) 

/ 




N 


signal (SIGINT, 


SIG IGN) ; 


/* ignore interrupts */ 




wait (&status) ; 


/* 


until the child is done */ 




signal (SIGINT, 



onintr) ; 


/* restore interrupts */ 


/ 



Why is this? Again, it’s not obvious, but not really difficult Suppose the pro- 
gram you call catches its own interrupts. If you interrupt the subprogram, it will 
get the signal and return to its main loop, and probably read from stdin. But 
the calling program will also pop out of its wait for the subprogram and read 
from stdin. Having two processes reading the same input is very unfortunate, 
since the system figuratively flips a coin to decide which should get each line of 
input. A simple way out is to have the parent program ignore interrupts until the 
child is done. This reasoning is reflected in the standard I/O library function 
system: 
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As an aside on declarations, the function signal ( ) obviously has a rather 
strange second argument. It is in fact a pointer to a function, and this is also the 
type of the signal routine itself. The two values SIG_IGN and SIG_DFL have 
the right type, but are chosen so they coincide with no possible actual functions. 
For the enthusiast, here is how they are defined for the Sun system — the 
definitions should be sufficiently ugly and nonportable to encourage use of the 
include file. 
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The Standard I/O Library 



Input and output are, strictly speaking, not an intrinsic part of the C programming 
language. Rather, the input and output functions are supplied by a library which 
comes with each implementation. 

This chapter describes the Standard I/O Library available to C programmers on 
Sun workstations. 



5.1. The Standard I/O 
Library 



The standard I/O library was designed with the following goals in mind: 

1. It must be as efficient as possible, both in time and in space, so that there 
will be no hesitation in using it, no matter how critical the application. 

2. It must be simple to use, and also free of the magic numbers and mysterious 
calls whose use mars the understandability and portability of many programs 
using older packages. 

3. The interface provided should be applicable on all machines, whether or not 
the programs which implement it are directly portable to other systems, or to 
non-Sun machines running a version of UNIX. 



5.2. Using the Standard I/O The stdio . h routines are in the normal C library, so no special library argu- 
Library ment must be declared in your program for linking. All names in the include file 

intended only for internal use begin with an underscore (_) to reduce the possi- 
bility of collision with a user name. The names intended to be visible outside the 
package are listed in Table 5-1. 

The routines in this package offer the convenience of automatic buffer allocation 
and output flushing where appropriate. 



The names stdin, stdout, and 
stderr are constants and may not 
be assigned values. They 
correspond to file descriptors 0, 1 
and 2, respectively. 



Any program which uses the Standard I/O Library must have the following line 
in the program source text, before using any of the functions in the library. 



♦include <stdio.h> 

. 



Putting this include statement in your program defines some macros and vari- 
ables for the program. 
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Table 5-1 Standard I/O Library Names Accessible to User Programs 



Name 


Description 


stdin 

.... . 


The name of the standard input file. This file is automatically connected at program 
startup time, and is the place from which a program reads its input 


stdout 


The name of the standard output file. This file is automatically connected at program 
startup time, and is the place to which a program writes its output. 


stderr 


The name of the standard error file. This file is automatically connected at program 
startup time, and is the place to which a program writes any error or diagnostic responses 
which should not clutter up the standard output. 


EOF 


is actually the value — 1. EOF is returned by the read routines upon encountering end-of-file 
or error conditions. 


NULL 


is a notation for the null pointer. Functions whose values are pointers return NULL to indi- 
cate an error. 


FILE 


is an abbreviation for the declaration: struct _iob and is a useful notation when declar- 
ing a pointer to a stream. 


BUFSIZ 


is the size suitable for a user-supplied input-output buffer. BUFSIZ is usually 1024. See the 
setbuf () function described below. 



The functions getc ( ) , getchar ( ) , putc () , putchar ( ) , feof ( ) , f er- 
ror ( ) , and f ileno ( ) are all defined as macros. Their descriptions appear 
later in this chapter. They are mentioned here to indicate that they cannot be 
redeclared. In addition, because they are macros and not functions, they cannot 
be passed as arguments to other functions, nor can their addresses be taken. 

The ‘Standard I/O Library’ is a collection of routines intended to provide 
efficient and portable I/O services for most C programs. The standard I/O library 
is available on each system that supports C, so programs that confine their system 
interactions to its facilities can be transported from one system to another essen- 
tially without change. 

This chapter describes the basics of the standard I/O library. Following chapters 
contain a fuller description of the capabilities and calling conventions of the 
functions in it. 

You could do I/O by calling the system routines directly. However, there is a 
‘standard I/O package’ that provides a high-level I/O access mechanism. This 
and the following chapters discuss the functions available in the standard I/O 
package. (An appendix discusses the raw interface to the operating system.) In 
general, you can get by using the standard I/O package and never need to use the 
raw system calls. 

The standard I/O package provides access to files in the system through a collec- 
tion of file descriptors that refer to structures for managing I/O buffering. The 
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first part of the discussion in this chapter describes those file descriptors that are 
defined automatically. Following sections describe how to get your own descrip- 
tors connected to files in the system. 

5.3. The Standard Input Three files are connected automatically when a SunOS program starts up. These 

and Standard Output files are called the standard input ( St din ) , the standard output ( s tdout ) , 

and the standard error ( s tder r ) . 

The very simplest standard I/O call for output is to use put char ( c) to put the 
character c on the standard output, which is normally the user’s screen. 

If the user redirected the standard output by using the > syntax on the command 
line, the standard output is redirected. For example, if you typed: 



r 


A 


tutorial% prog > outputfile 

V 


> 



on the command line, the standard output from prog is written to outputfile and 
the program is unaware that the standard output is going to a file instead of the 
screen, outputfile is created if it doesn’t exist; if it already exists, its previous 
contents are overwritten. 

Similarly, you can send the standard output from a program through a pipe with 
the command line: 



tutorial% prog | otherprog 

Vs > 



and the standard output of prog goes into the standard input of otherprog. 



Reading Standard Input and The simplest input mechanism is to read from the ‘standard input,’ which is gen- 

Writing Standard Output erally the user’s keyboard. The function get char ( ) returns the next input 

character each time it is called. A file may be substituted for the keyboard by 
using the < convention (input redirection): if prog uses get char ( ) , the com- 
mand line 





tutorial% prog < filename 

J 



makes prog read from the file specified by filename , instead of from the key- 
board. prog itself need know nothing about where its input is coming from. 
This is also true if the input comes from another program through the pipe 
mechanism: 



f 


> 


tutorial% otherprog | prog 




v 


j 



provides the standard input for prog from the standard output (see above) of 
otherprog. 
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getchar ( ) returns the value EOF when it encounters the end of file (or an 
error) on whatever you are reading. The value of EOF is normally defined to be 
-1, but it is unwise to take any advantage of that knowledge. As will become 
clear shortly, this value is automatically defined for you when you compile a pro- 
gram, and need not be of any concern. 

The function printf ( ) , which formats output in various ways, uses the same 
mechanism as putchar ( ) does, so calls to printf ( ) and putchar ( ) may 
be intermixed in any order; the output appears in the order of the calls. 

Similarly, the function scanf ( ) provides for formatted input conversion, 
scanf ( ) reads the standard input and breaks it up into strings, numbers, etc., as 
desired, scanf ( ) uses the same mechanism as getchar ( ) , so calls to them 
may also be intermixed. 

Many programs read only one input and write one output; for such programs I/O 
with getchar ( ) , putchar ( ) , scanf ( ) , and printf ( ) may be entirely 
adequate, and it is almost always enough to get started. This is particularly true 
if the SunOS pipe facility is used to connect the output of one program to the 
input of another. For example, the following program strips out all ASCII control 
characters from its input (except for newline and tab). 



#include <stdio.h> 

main() /* ccstrip: strip non-graphic characters */ 

{ 

■ int e; 

while ( (c = getchar O) != EOF) 

if <(c >= ' ' && c < 0177) 1| c == ' \t' | | c == '.\n') 

putchar <c) ; 

exit (0) ; 

} ' : v ' : ] Iff III II lllllllllllillll I II III || || : .... | 

"" ^ :i " ■■ : ' : : ■ ^ V : : ' ' ' ■ : : : j ±, - :V; _ : : _ - ■ __ i_ __ 1- : _ . i- - _ j-ll. 1 1- jj. ■ ! ^ ' ' ' " ^ ! ! ^ ^ ^ ^ ) 



You would use the program like this: 





tutorial% cat infile | ccstrip > output 
\ - 



If you need to treat multiple files, you can use cat to collect the files for you: 



. 

tutorial% cat filel file2 ... | ccstrip > output 

\ / 



and thus avoid learning how to access files from a program. By the way, the call 
to exit () at the end is not necessary to make the program work properly, but it 
assures that any caller of the program will see a normal termination status (con- 
ventionally 0) from the program when it completes. Section 3.3 discusses return- 
ing status in more detail. 
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5.4. Error Handling — stderr is assigned to a program in the same way that stdin and stdout are. 

stderr and exit ( ) Output written on stderr appears on the user’s terminal even if the standard 

output is redirected, unless the standard error is also redirected. For example, the 
command wc writes its diagnostics on stderr instead of stdout so that if one 
of the files can’t be accessed for some reason, the message finds its way to the 
user’s terminal instead of disappearing down a pipe or into an output file. 

The argument of exit ( ) is made available to whatever process called the pro- 
cess that is exiting (see Section 3.3), so the success or failure of the program can 
be tested by another program that uses this one as a subprocess. By convention, 
a return value of 0 indicates that all is well; nonzero values indicate abnormal 
situations. 

exit ( ) itself calls f close ( ) for each open output file, to flush out any buf- 
fered output, then calls a routine named _exit ( ) . The function _exit ( ) ter- 
minates the program immediately without any buffer flushing; it may be called 
directly if desired. 

5.5. Miscellaneous I/O The standard I/O library provides several other I/O functions besides those illus- 

Functions trated above. 

Normally, output with put c ( ) and such is buffered — use f f lush ( f p ) to 
force it out immediately. 

f scant ( ) is identical to scant ( ) , except that its first argument is a file 
pointer that specifies the file from which the input comes; it returns EOF at end of 
file. 

The functions s scant ( ) and sprint f () are identical to f scant () and 
f print f ( ) , except that the first argument names a character string instead of a 
file pointer. The conversion is done from the string for sscanf ( ) and into it 
for sprint f ( ) , and no input or output is done. 

f gets (but, size, fp) copies the next line from stream fp, up to and 
including a newline, into but ; at most size-1 characters are copied; it returns 
NULL at end of file, fput s (buf , fp) writes the string in buf onto file or 
stdio stream fp. 

Note The "stream" referred to above is not related to UNIX System V streams. 

The functions gets ( ) and puts ( ) work like f gets ( ) and fputs ( ) , but 
they default to operation with stdin and stdout, respectively. The macro 
ungetc (c , f p) ‘pushes back’ the character c onto the input stream f p; a sub- 
sequent call to getc ( ) , f scanf ( ) , and so on will encounter c. Only one 
character of pushback is guaranteed to work. 
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Accessing Files Through Standard I/O 



Previous examples have all read the standard input and written the standard out- 
put, which we have assumed are magically predefined. The next step is to write a 
program that accesses a file that is not already connected to the program. One 
simple example is wc, which counts the lines, words and characters in a set of 
files. For instance, the command 



r 


— 


tutorial% wc x.c y.c 




V 


J 



displays the number of lines, words and characters in x . c and y . c and the 
totals. 

The question is how to arrange for the named files to be read — that is, how to 
connect the filenames to the I/O statements which actually read the data. 

The rules are simple — you have to open a file by the standard library function 
f open ( ) before it can be read from or written to. f open ( ) takes an external 
name (like x.cor y . c) , does some housekeeping and negotiation with the 
operating system, and returns a pointer which must be used in subsequent reads 
or writes of the file. 

This pointer, called a FILE pointer, to a structure which contains information 
about the file, such as the location of a buffer, the current character position in 
the buffer, whether the file is being read or written, and the like. The only 
declaration needed for a file pointer is exemplified by 







s 


FILE 


*fp, *fopen(); 




v 




.. . ^ 



This says that fp is a pointer to a FILE, and f open ( ) returns a pointer to a 
FILE. 

The actual call to fopen ( ) in a program has the form: 



J 



fp = fopen (name, mode); 
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The next thing needed is a way to read or write the file once it is open. There are 
several possibilities, of which getc ( ) and putc ( ) are the simplest, getc { ) 
returns the next character from a file; it needs the file pointer to tell it what file. 
Thus 



f N 

c = getc(fp) 

^ / 



places in c the next character from the file referred to by fp; it returns EOF when 
it reaches end of file, putc ( ) is the inverse of getc ( ) : 



putc (c. 



fp) 



puts the character c on the file f p and returns c as its value, getc ( ) and 
putc ( ) return EOF on error. 

When a program is started, three streams are opened automatically, and file 
pointers are provided for them. These streams are the standard input, the stan- 
dard output, and the standard error output; the corresponding file pointers are 
called stdin, stdout, and stderr. Normally these are all connected to the 
terminal, but may be redirected to files or pipes as described in Section 5.3 . 
stdin, stdout and stderr are predefined in the I/O library as the standard 
input, output and error files; they may be used anywhere an object of type 
FILE * can be. They are constants, however, not variables, so don’t try to 
assign to them. 

With some of the preliminaries out of the way, we can now write wc . The basic 
design is one that has been found convenient for many programs: if there are 
command-line arguments, they are processed in order. If there are no arguments, 
the standard input is processed. This way the program can be used standalone or 
as part of a larger activity. 
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finclude <stdio.h> 

main (argc, argv) /* wc: count lines, words, chars */ 
int argc; 
char *argv[ ]; 

{ 

int c, i, inword; 

FILE *fp, *fopen{); 

long linect, wordct, charct; 

long t linect = 0, twordct = 0, tcharct = 0; 

i = 1; 
fp ~ stdin; 

■. do { ■ ■ 

if (argc > 1 && <fp*f open (argv [i] , ”r”) ) — NULL) { 
fprintf (stderr, "wc: can't open %s\n", argv(ij); 
continue; 

} 

linect - wordct ~ charct = inword - 0; 
while ( (c = getc(fp)) l- EOF) { 
charct++; 
if (c — ' \n r ) 
linect ++; 

if (c == ' ' | [ c == '\t T I I c ~= f \n') 

inword - 0; 

else if (inword == 0) { 
inword - 1 ; 
wordct+t; 

1 

} 

printf ("%71d %71d %71d", linect, wordct, charct) ; : . 

printf (argc > 1 ? ” %s\n" : "\h", argv [i 3 ) 7 

fclose (fp) ; 

tlinect += linect; 

twordct +~ wordct; 

tcharct += charct; 

} while (++i < argc) ; 
if (argc > 2) 

printf ("%71d %71d %71d total\n M , tlinect, twordct, tcharct); 
exit (0) ; 

} 

The function fprintf ( ) is identical to printf () , except that the first argu- 
ment is a file pointer that specifies the file to be written. 

The function fclose ( ) is the inverse of f open ( ) ; it breaks the connection 
between the file pointer and the external name that was established by f open ( ) , 
freeing the file pointer for another file. There is a limit, depending on available 
memory, on the number of files that a program may have open simultaneously, 
so you should free things when they are no longer needed. There is another rea- 
son to call f close ( ) on an output file — it flushes the buffer in which 
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putc ( ) collects output. Each file is closed automatically when a program ter- 
minates normally. 

6.1. Accessing Files Several stdio routines needed to perform file I/O housekeeping and access 

functions are described below: 



f open ( ) — Open a File 



r 




FILE * fopen (filename , type) 




char * filename; 




char *type; 




^ - - - - - 


/ 



filename is a character string that specifies the name of the file. 

type is a character string (not a single character) that specifies the access 

mode of the file, type can be one of: 
r reopen the file for reading, 
w reopen the file for writing, 
a reopen the file for appending. 

f open ( ) opens the file and, if needed, allocates a buffer for it. In 
addition, each mode specification may be followed by a + sign to 
open the file for reading and writing. Both reads and writes may be 
used on read/write streams, with the limitation that an f seek, 
rewind ( ) , or reading end-of-file must be used between a read and 
a write or vice versa. The value returned is a file pointer. If it is 
NULL the attempt to open the file failed. 



Figure 6-1 Example of Using f open ( ) 

demo () 
l 

. :file * ^ A ' : ; C- r’- ^ =|^ s; 1 ' ; N -fK j ■ : W;' 

/* open the file */ 

if ( (fp = fopen ("/usr/lib/tmac.tmac.e", "r")) == NULL) 
printf ("Can't open /usr/lib/tmac/tmac ,e\n") ; 

else 

... go ahead and work with the file 

} /* end of the demo function */ 

If a file that you open for writing or appending does not exist, it is created (if pos- 
sible). Opening an existing file for writing discards the old contents. Trying to 
read a file that does not exist is an error, and there may be other causes of error as 
well (like trying to read a file without read permission). If there is an error, 
fopen () returns the null pointer value NULL. 
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f reopen ( ) — Reopen a File 







FILE *f reopen (filename, type, ioptr) 




char * filename; 




char *type; 




FILE * ioptr ; 









The stream named by ioptr is closed, if necessary, and then reopened as if by 
f open ( ) . If the attempt to open fails, NULL is returned; otherwise ioptr is 
returned, which now refers to die new file. Often the reopened stream is stdin 
or stdout. The filename and type parameters are as for fopen ( ) . 
filename is a character string that specifies the name of the file. 

type is a character string (not a single character) that specifies the access 

mode of the file, type can be one of; 
r reopen the file for reading, 
w reopen the file for writing, 
a reopen the file for appending. 

ioptr is a pointer to the existing stream which is to be closed. 

The value of the f reopen ( ) function is a file pointer. If the value of the file 
pointer is NULL, the attempt to open the file failed. 



Figure 6-2 Example of Using freopen() 



demo < ) 

{ ' ; : g||^ | i; : 

FILE * f reopen () ; 

/* re-open the file */. 

if <(fp = freopen ("/lib/ftncterrs", "r”, fp) ) == NULL) 
printf ("Can't open /lib/ftncterrs\n") ; 

else 

. . . go ahead and work with the file 
} /* end of the demo function */ 



fflushO — Flush Stream The fflushO function flushes the stream buffer for a given file pointer. The 
Buffer interface to fflushO is: 



f flush (ioptr) 

FILE *fp; 

V. > 



Any buffered information on the output stream designated by ioptr is written 
out to the file. Common use is to f flush ( stdout ) so that the prompt 
appears immediately. 

Output files are normally buffered if they are not directed to a screen, alwaysst- 
doutis The stderr file usually starts off unbuffered, and remains unbuffered 
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f close ( ) 



setbuf ( ) 

File I/O 



unless the setbuf ( ) function is used, or unless the file is reopened. 
Close A File The f close ( ) function closes an open file. The interface definition is: 





\ 


fclose (ioptr) 




FILE *ioptr; 






j 



The file designated by ioptr is closed, after any buffers associated with that 
file have been written out. 

Any buffers allocated to the file are freed. 

When a C program terminates normally (in a controlled fashion), f close ( ) 
requests are issued automatically. 

Set Buffer for The setbuf ( ) function sets up a buffer for an open file. The user can desig- 
nate a buffer different from the one which the run-time library chooses, or the 
user can select no buffer at all. The interface to setbuf ( ) is: 



r 




setbuf (ioptr, buf) 




FILE *ioptr; 




char *buf; 




v 


J 



The setbuf ( ) function is used after a file is opened, but before any I/O 
transfers have been made to that file. 

If the buf parameter is NULL, the stream becomes unbuffered. Otherwise, the 
buffer supplied is used. The buffer buf must be a sufficiendy large character 
array. The usual way to assure this is to declare the buffer: 



— 
char buf [BUFSIZ] ; 

/ 



Here’s an example of setbuf ( ) usage: 
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f ileno ( ) 

Descriptor 



Figure 6-3 Example of Using setbuf ( ) 

rv “ : 7 ” 7 ~ > 

demo O 
{ 

FILE *f open; 

/* open the file */ 

if ((fp = fopen ( "/lib/pascterrs ” , r r')) == NULL) 

printf ("Can't open /lib/pascterrsYn” ) ; 

■: el : se' .■ - ■■ ■ ■ ■ . ■ ■ . . 

/* make the file unbuffered */ 
setbuf (fp, NULL) ; 

} /* end of the demo function */ 

^ :: ^ ■ : . | | j " 1 : : 1 j 1 1111 ■ 1 jj 1 ! : | - / . ' ! jj 11 ■ 111. j| 1 1 M. 1 j I _ ^ - ^ 



Obtain File 



The f ileno ( ) function returns an integer value which is the file descriptor 
associated with the file. 



r 




int f ileno (ioptr) 




FILE *ioptr; 




v 


> 



f ileno ( ) is typically used when a file has been previously opened with 
fopen ( ) but you want to use a function on it that requires a file descriptor 
instead of a file pointer. 

Here’s an example of f ileno ( ) usage: 



Figure 6-4 Example of Using f ileno ( ) 

; ‘ 

demo ( ) 

FILE * fopen; 
int filemum; 

/* open a file */ 

if ( (fp g* fopen ("/etc/passwd", ' r' ) ) ===== NULL) 
printf ("Can't open /etc/passwd\n") ; 

else 

/* get the file number */ 
file__num « f ileno (fp) ; 

} /* end of the demo function */ 
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rewind () — Rewind a The rewind () function rewinds the stream designated by the ioptr param- 

Stream eter. 



r 




rewind (ioptr) 




FILE *ioptr; 




l . . - 





If you want to rewind a file for reading, use f reopen ( ) . 
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Character I/O 



This section describes those macros and functions which are concerned with 
reading and writing characters from and to streams. 

getc() Macro — Get a ThegetcO macro gets a character from a file. The definition is: 

Character from a File 




The getc ( > macro obtains the next character from the stream designated by 
f p. fp is a file pointer such as is returned by the f open ( ) function, or is a 
name such as stdin. 

When the end of file is reached, the integer EOF is returned. The character \ 0 is 
a valid character from getc ( ) . 

Note that getc ( ) is a macro, not a function. 




sun 

microsystems 



41 



Revision A of 27 March, 1990 




42 C Programmer’s Guide 



Figure 7-1 Example of Using getc() 



main (argc, argv) 

int argc; 

char *argv I]'-/?: 

{ 

■ . FILE *£p; 

: int num_char “ 0; 

int c; ; 

if (<fp = fopen (argv [13, "r”) ) == NULL) . 
print f ("Can't open %s\n”, argv [1]); 

■ else 

/* count characters in a file */ 
while (getc(fp) != EOF) 
num_char++; 

} /* end of the count function */ 

v J 

f getc ( ) Function — Get The f getc ( ) function obtains a single character from a file. The interface 

Character from File definition is: 



r 


A 


int fgetc (ioptr) 




FILE *ioptr; 






J 



f get c ( ) obtains the next character from the stream designated by ioptr. 
iopt r is a file descriptor such as is returned by the fopen ( ) function, or is a 
name such as stdin. 

When the end of file is reached, the integer EOF is returned. The character \ 0 is 
a valid character from f get c ( ) . 

fgetc () is a genuine function, as opposed to the getc ( ) macro. This means 
that fgetc ( ) can be pointed to and passed as an argument to another function. 
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Figure 7-2 Example of Using fgetc() 




get char ( ) Macro — Get a The get char ( ) macro obtains a single character from the standard input. The 

Character from Standard interface to get char ( ) is: 

Input 



The getchar ( ) macro is a shorthand notation for 




Note that getchar ( ) is a macro, not a function. 
Figure 7-3 Example of Using getchar ( ) 
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f gets ( ) — Read a String The fget s ( ) function reads a string from a specified file. The interface 
from a File definition is: 



r 


-v 


char *fgets(s, n, ioptr) 




char *s; 




int n ; 




FILE *ioptr; 




V 


J 



The f gets ( ) function reads up to n-1 characters from the stream designated 
by ioptr into the character array pointed to by s. 

Note Be careful that s can accomodate n characters! 

The read terminates when a newline character is read. The newline character is 
placed in the buffer. The last character read is always followed by a null charac- 
ter in the character array. 

The f get s ( ) function returns its first argument, or NULL if an error or an end 
of file was encountered. 



Figure 7-4 Example of Using f get s ( ) 




ungetcf) — Push a The ungetc ( ) function pushes a single character back onto a stream. The 

Character Back on a Stream interface definition is: 



r 




a 


ungetc ( c , 


ioptr) 




char 


c; 




FILE 


* ioptr; 




v 




J 



The ungetc ( ) function pushes the character argument, c, back onto the input 
stream designated by ioptr. 




sun 

microsystems 



Revision A of 27 March, 1990 







Chapter 7 — Character I/O 45 



Only one character may be pushed back between two reads. 



Figure 7-5 Example of Using ungetc() 

r . 1 "• 1 _ . . rr - - ■ . ' ■ • T " ■ x 

main <) 

f ' % : Pi : ) 5 | : I j . > . f ■ • : 

. ' % iht': ' ■ ch ; ' " ■ t : Ji; % sSi : . Si. .ft S ( . f f •: 5 ;f ' > [ i f ■ • •; • 

foliar digits ‘ : /£ : 

int idx = 0; 

/* read number from standard input */ 

while ( (ch = getchar ()) != EOF && idx < 255) 

if (ch >= HI && ch <- / 9') f 
tf : f digits [idx++| = ch; 
else { 

unget c (ch, stdin ) ; 
break;. 



} /* end of the read number function */ 



put c ( ) Macro — Put a The put c ( ) macro puts a single character to a specified file. The interface 

Character to a File definition is: 



f 


\ 


putc ( c f ioptr) 




char c; 




FILE *ioptr; 




^ 





The putc ( ) macro writes the character c onto the output stream designated by 
ioptr, where ioptr is a file pointer such as is returned by the f open ( ) func- 
tion, oris a name such as stdout or stderr. 

The character c is normally returned as a value from the macro, but if an error 
occurs during the transfer, the value EOF is returned. 

Note that put c ( ) is a macro, not a function. 



: N 

main ( ) 

< 

char ch; 

/* copy stdin to stdout */ 
while ( (ch = getchar 0) != EOF) 

putc(ch, stdout); 



} /* end of the copy function */ 

: " - : / ; ; ; ^ .f f Ptt tf f f f Ilf f * MmMMtM _ : : . _ _ __ ■ , , _ __ 
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Remember that putc ( ) normally buffers its output; terminal I/O is not properly 
synchronized unless this buffering is defeated. Use f flush to do this. 

f putc ( ) Function — Put a The fputc ( ) function outputs a single character to a specified file. The inter- 
Character to a File face definition is: 




The fputc ( ) function writes the character c onto the stream designated by 
ioptr, where ioptr is a file pointer such as is returned by the f open ( ) func- 
tion, or is a name such as stdout or stderr. 

The character c is normally returned as a value from the function, but if an error 
occurs during the transfer, the value EOF is returned. 

fputc ( ) is a genuine function, as opposed to the putc ( ) macro. This means 
that fputc ( ) can be pointed to, passed as an argument to another function, and 
so on. 

Figure 7-6 Example of Using fputc () 




put char ( ) Macro — Put a The put char ( ) macro puts a single character to the standard output file. The 
Character to Standard Output interface definition is: 




The put char ( ) macro is a shorthand notation for 
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Note that put char ( ) is a macro, not a function. 



Figure 7-7 



f put s ( ) — Put a String to a 
File 



Figure 7-8 



f eof ( ) — Test for End Of 
File 



Example of Using put char () 



main () 

char ■ ch; ■ : V-' ■ /.V ,7 




7 /* copy stdin to stdcut 
while { (ch = getcharO ) != EOF) 

• putchar (ch) ; 


*/ ^ 


} /* end of the copy function */ 




f put s ( ) writes a character string to a file. The interface definition is: 


— 

fputs(s, ioptr) 
char *s; 

FILE *ioptr; 

V . .. . 


N 

J 


The f put s ( ) function writes the null-terminated character string s 
character array) to the stream designated by ioptr. 


(which is a 


f put s ( ) does not append a newline to the string, 
f put s ( ) does not return a value. 




Example of Using f puts ( ) 




main () 
f 

char line [256] ; 




/* copy lines from stdin to stdout 
while ( (f gets (line, 256, stdin)) !== NULL) 
fputs (line, stdout); 


*/ 


} /* end of the copy function */ 




The f eof ( ) function checks for an end of file on a specified file. The interface 
definition is: 


feof (ioptr) 

FILE *ioptr; 

V 
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The f eof ( ) function returns a nonzero value if an end-of-file has occurred on 
the stream designated by ioptr. 

7.1. Formatted Input and The C run-time library provides extensive facilities for formatted conversions of 
Output character strings to numeric data, and for the formatted conversion of numeric 

data to character strings. Conversions can be done between the standard input or 
standard output, an arbitrary file, or strings in memory. The subsections follow- 
ing give detailed descriptions of these facilities. 

Formatted Output There are three variations of the formatted output functions: they are all similar 

Conversions in their actions, the only difference being the destination of the formatted string. 



r 


A 


printf (format, arg^ • • •) 




char ^format; 




L. 


J 



printf ( ) writes the formatted string to the standard output. 



r 


\ 


fprintf (ioptr, format, arg , . . .) 




FILE * ioptr; 




char ^format; 




L. 


) 



f print f ( ) writes the formatted string to the file designated by ioptr. 



r 


a 


sprintf(s, format, arg^ . . .) 




char *s; 




char ^format; 




v 


j 



sprint f ( ) stores the formatted string into a character string (character array) 
in memory. 

Formatted Input Conversions The scanf ( ) , f scanf ( ) , and sscanf ( ) functions are the equivalents of the 

printf ( ) functions described above, except that the scanf ( ) functions per- 
form conversions from character strings to data in memory. They are thus used 
for reading formatted information instead of writing it. 

There are three variations of the scanf ( ) function: 



— 

scanf (format, arg^ . . .) 
char *format; 

/ 



scanf ( ) reads the formatted string from the standard input. 
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t 




. 


f scanf (ioptr, format, arg^ . . 


.) 




FILE *ioptr; 






char ^format; 






s 




> 



f scanf ( ) reads the formatted string from the file designated by ioptr. 



r 






> 


sscanf (s. 


format, arg , . 


.) 




char 


*s; 






char 


* format ; 






V 






> 



sscanf ( ) gets the formatted string from a character string (character array) in 
memory. 

All six print and scan functions accept a format argument, followed by 
zero or more arg^ arguments. 

The format argument is a template, in the form of a character string. The for- 
mat character string consists of two kinds of objects: 

□ It can contain fixed parts which are sent to the destination unchanged 
(for formatted output) or match characters in the input source (for 
formatted input). 

□ It can also contain conversion specifications, which indicate how the 
corresponding arg are to be converted and placed into the final 
formatted output string, or recognized in the input, and converted to 
internal form and placed in the location pointed to by the arg^. 

Conversion Specifications A conversion specification is marked by a percent sign %, and ends with a 

conversion character. In between the % sign and the conversion character, there 
can be modifiers. These modifiers are described below after the descriptions of 
the conversion characters. Any character in a format that is not part of a conver- 
sion specification is passed or recognized as is. 

Here is a printf ( ) call with a simple string template and no conversion 
specifications: 



The Format Control 
Templates 



printf ("Calling occupants of interactive space\n") ; 



This example simply prints the quoted string on the standard output. 

The following paragraphs describe the effects of the conversion characters. 

There are also modifiers for the conversion specifications, and these are described 
below. 
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d — Decimal Conversion A d conversion character specifies that the associated argument is converted to 

(or from) decimal notation. 

Figure 7-9 Example of d Format Specification 




When the above program is run, it generates the result: 




o — Octal Conversion A conversion character of o specifies that the associated argument is converted to 

(or from) unsigned octal notation. The resulting output string does not contain a 
leading zero. It is the responsibility of the programmer to insert the leading zero 
"manually" as part of the format string, if that is what is required. 

Figure 7-10 Example of o Format Specification 




When the above program is run, it generates the result: 




Note that the program explicitly places the digit "0" in the generated number. 

x — Hexadecimal Conversion A conversion character of x specifies that the associated argument is converted to 

(or from) unsigned hexadecimal notation. The resulting output string does not 
contain a leading "Ox". It is the responsibility of the programmer to insert the 
leading "Ox" "manually", as part of the format string, if that is what is required. 
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Figure 7-11 Example of x Format Specification 




Note that the programmer explicitly coded the "Ox" in the generated number. 

h — Short Conversion on Input A conversion character of h is used only for formatted input, and specifies that 
Only the associated argument is a pointer to a short int data item. 

u — Unsigned Decimal A conversion character of u specifies that the associated argument is converted to 

Conversion (or from) unsigned decimal notation. 

Figure 7-12 Example of u Format Specification 




c — Character Conversion A conversion character of c specifies that the associated argument is to be con- 

verted to (or from) a single character. 
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Figure 7-13 Example of c Format Specification 

• — ■ — ■ — : — : — — *\ 

main () 

C V . - ; ■ f-1 •• • /. 

static char data [10] = •’Hi there !"; 

print f C "Parts of data are: %c %c %c\n", 

data[0], data [8']/ data [4]); 



. } /* End of the demo function */ 

>■■■■■ ■ • ■ •■■■■=■ ■■ * 



When the above program is run, it generates the result: 




s — String Conversion A conversion character of s specifies that the associated argument is a string. 

Characters from the string are printed until a null character is found, or until the 
number of characters indicated by the precision specification (see below) are 
used up. 

Figure 7-14 Example of s Format Specification 



main () 

1 

static char data f] *• "Hello, World!"; 




printf ("The value of data is: *%s'\n", data); 




} /* End of the demo function */ 

V 1 : : : ' : 


liiM 


When the above program is run, it generates the result: 


r 

The value of data is: 'Hello, World!' 

^ - - - 


N 

J 



e — Exponential Floating A conversion character of e specifies that the associated argument is assumed to 

Conversion be a float or a double. It is converted to (or from) a decimal exponential 

notation of the form 



f 


a 


[-]m.nnnnnnnE [±]xx 




s 


/ 



where the length of the string of n’s is specified by the precision. The default pre- 
cision is six decimal places. 
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Figure 7-15 Example of e Format Specification 




When the above program is run, it generates the result: 




f — Fractional Floating A conversion character of f specifies that the associated argument is assumed to 

Conversion be a float or a double. It is converted to (or from) a fixed-decimal notation. 




where the length of the string of n’s is specified by the precision. The default 
precision is six decimal places. The precision does not determine the number of 
digits printed in f format, but the number of decimal places displayed. 



Figure 7-16 Example of £ Format Specification 




When the above program is run, it generates the result: 




g — Adaptable Floating A conversion character of g specifies that the associated argument is to be con- 

Conversion verted to (or from) either e or f format, depending upon which is the shorter. 

Non-significant zeros are not printed in g format. This is similar to FORTRAN’S 
G format conversion. 
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Figure 7-17 Example of g Format Specification 



r • • ■ ■ 

main {) 

III!!! ! | ! 1 1 llll |ii!| |||| |||| | ill 1 || 1 j||||l | fll | • :;||l||l| l||| |l l 

float 

data •• i2;^; , 456; • 




pfi.ntf ("The value of data is; %g\n" # data); 




> /* End of the. demo function */: 




When the above program is run, it generates the result: 




/ 

The value of data is: 123.456 


\ 


v 


j 



Literal Character Output If the character which follows the % sign is not a conversion character, that char- 

acter is printed as is. Thus, to print a % sign, use a format conversion of %%. 



Figure 7-18 Example of Literal Character Output 

v 

main () 

| 1 1 §||| : III II III Illllll lllllllllllllll | . | 

int 

data - 25; 

printf ("The value of data is: %y %%\n", data) ; 



} /* End of the demo function */ 



V-xxxxxXxxX;^^ xxxxxx^xox^xx xxx^ 

When the above program is run, it generates the result: 




r 

The value of data is : y % 


"N 




-J 



The two percent signs are displayed as one, and the unknown conversion charac- 
ter (y) is output as is. The value of the data variable in the output list is simply 
ignored, since no conversion specification in the format required data. 

Optional Format Modifiers Between the % sign and the format conversion letters as defined above, there may 

be some optional information. The characters which may appear in these posi- 
tions are described below. 
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Left Justify Field 



Minimum Field Width and 
Precision Specifications 



A minus sign (-) appearing before the conversion character specifies that the 
argument is to be left-justified in the output field. The minus sign is optional. 

After the minus sign can appear width and precision specifications, as described 
next. 

The form of the optional field width and precision specifications are: 

□ a digit string, which specifies a minimum field width. The converted 
number is printed in a field at least this wide, and wider if required. 
If the converted argument has fewer characters than the field width, 
it is padded on the left (or on the right, if a minus sign was given) 
with enough padding characters to make up the specified field width. 
The padding character is normally a space. If the field width is 
specified with a leading zero the output field is padded with zeros. 

□ a period character, which separates the field width from the next 
digit string. 

□ a digit string, which is the precision. The precision means one of 
two things. In the case of a float or a double argument, the pre- 
cision is the number of digits to be printed to the right of the decimal 
point In the case of a string argument, the precision is the number 
of characters to be printed from the string. 

The examples below show the way that the justification, width, and precision 
specifications apply to string values when they are output. The value to be 
printed is the string "Wizard", which is six characters long. It is printed in a 
variety of format specifications, and there are vertical bars at either end of the 
field to show the extent of the field. 



Figure 7-19 Example of Field Width Specifications 



main {) 



static char data [] = "Wizard"; 



printf ("data 
printf ("data 
printf ("data 
printf ("data 
printf ("data 
printf ("data 
printf ("dcita 



in %%4s format is: |%4s : |\n”, data); 
in %%-4s i.brmat is : | %-4s: I Vn", data) ; 
in %%10s format is: |%10s;f\n", data); 
in %%-10s format is: 1 %— 10s : 1 \n", data); 
in %%10.4s format is: \ %10 . 4s: I \n", data); 

in %%-ld . 4s format is : 1 %-tj:6 . 4s : | \n", data) ; 
in %%.4s format is: | % .4s : | \n", data) ; 



/* End of the demo function •*/ 



When the above program is run, it generates the results: 
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Length Modifier 



data 


in 


data 


in 


data 


in 


data 


in 


data 


in 


data 


in 


data 


in 



%4s format is: |Wizard| 

%-4s format is: |Wizard| 

%10s format is: I Wizard] 
%-10s format is: (Wizard I 

%10.4s format is: | Wizal 

%-10.4s format is: |Wiza I 

%.4s format is: | Wizal 



If the conversion specification is preceded by a lx, it means that the associated 
argument is a long while If indicates a double. If no length modifier pre- 
cedes the conversion specification, the associated argument is assumed to be an 
int. A lone 1 preceding the conversion specification is ignored in Sun C 
because ints and longs are the same. 

In calls to scanf ( ) , the arguments are pointers. Sizes in format specifiers must 
be correct: use %f for floats and % If for doubles. 
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String-Handling Functions 



The C programming language has no language-defined facilities for manipulating 
character string data. The C library does, however, provide a fairly rich set of 
primitives for manipulating character strings. 

This chapter discusses three major areas relating to string handling: 

□ Macros for classifying characters (is a character, uppercase, letter, 
digit, and such), plus macros for doing some minimal conversions 
(convert uppercase to lowercase). 

□ Functions for handling null-terminated strings. 

□ Functions for handling bit strings and byte strings. 

8.1. Character The following macros classify ASCII-coded integer values. Each is a predicate 

Classification returning nonzero for true, zero for false. isascii() is defined for all integer 

values; the rest are defined only where isascii (c) is true and on the single 
non-ASCII value EOF(see stdio( 3S)). 

You should have the line: 



♦include <ctype.h> 



at the beginning of any program unit that uses these macros. 



isalpha ( ) — Is Character 
Alphabetic 

isupper ( ) — Is Character 
Uppercase Letter 
is lower ( ) — Is Character 
Lowercase Letter 
isdigit ( ) — Is Character 
Decimal Digit 



isalpha (c) 
isupper (c) 
islower (c) 
isdigit (c) 



c is a letter — a through z or A through Z. 
c is an upper case letter — A through Z. 
c is a lower case letter — a through z. 
c is a digit — 0 through 9. 
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isxdigit ( ) — Is Character 
Hexadecimal Digit 

isalnum() — Is Character 

Letter or Digit 

isspace ( ) — Is Character 

Whitespace 

ispunctO — Is Character 
Punctuation 

i sprint () — Is Character 
Printable 

iscnt rl ( ) — Is Character 
Control Character 



isxdigit (c) c is a hexadecimal digit — 0 through 9, a through f , or A 
through F. 

isalnum ( c) c is an alphanumeric character, that is, c is a letter or a digit. 

isspace (c) c is a space, tab, carriage return, newline, or formfeed. 

ispunct ( c) c is a punctuation character (neither control nor alphanumeric) 

i sprint ( c) c is a printing character, such as ASCII characters 0x20 (space) 
through 0x7E (tilde). 

iscntrl (c) c is a delete character (0x7F) or an ordinary control character 
(less than 0x20). 



isascii() — Is Character 
an ascu Character 
i sgraph ( ) — Is Character a 
Visible Graphic 



isascii ( c) c is an ASCII character less than 0x80. 

i s graph ( c ) c is a visible graphic character, an ASCII character code from 
0x21 (exclamation mark) through 0x7E (tilde). 



8.2. Character Conversion 
Macros 

toupper ( ) — Convert 
Lowercase to Uppercase 



These macros perform simple conversions on single characters. 

toupper ( c) converts c to its upper-case equivalent. Note that this only works 
as expected if c is known to be a lower-case character to start with (presumably 
checked by is lower ( ) ). 



tolower ( ) — Convert tolower ( c ) converts c to its lower-case equivalent. Note that this only works 

Uppercase to Lowercase as expected if c is known to be an uppercase character to start with (presumably 

checked by is upper ( ) ). 



toascii ( ) — Ensure toascii ( c) masks c with the value 0x7F so that its result is guaranteed to be 

Character is ASCII an ASCII character in the range 0 thru 0x7F. 



8.3. Functions for Handling 
Null-T erminated 
Strings 



Null-terminated strings are arrays of characters. A correctly formed string has a 
zero (ASCII NUL) byte at the end to act as a terminator. All string handling rou- 
tines and I/O routines conform to these semantics. C builds in this notion when a 
programmer writes a string constant — the compiler correctly adds the null byte 
at the end of the string. Suppose you have this declaration in your program: 





char greetings!] = "Hi There!”; 

V / 
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Such a string appears in memory as: 

Figure 8-1 Layout of Null-Terminated String in Memory 



H 


i 




T 


h 


e 


r 


e 


! 


\ o 



Functions described in this section operate on null-terminated strings. They do 
not check for overflow of any receiving string. 

You must have the line: 



r 


N 


finclude <strings.h> 






J 



at the beginning of any program unit that uses the functions described here. 



Null Pointers versus Null On Sun workstations (and on most other machines), you cannot use a zero 

Strings pointer to indicate a null string. Dereferencing a null pointer is an error and 

results in aborting the program. If you wish to indicate a null string, you must 
have a pointer that points to an explicit null string. 

Programmers using NULL to represent an empty string should be aware that such 
programs work by coincidence, if at all, rather than by intent and should be 
aware that testing for zero pointers is inherently nonportable. 



strlenO — Find Length of 
String 



— 




strlen (s) 




char *s; 




V 


j 



strlen ( ) returns the number of non-null characters in s. 



strcmpO and strncmpO 

— Compare Strings 



strcmp (string_l, string_2) 
char *string_l, *string_2; 



r 




strncmp (string_l, string__2, n) 




char *string_l, *string_2; 




^ 


j 



strcmp ( ) compares its arguments and returns an integer greater than, equal to, 
or less than 0, according as stringl is lexicographically greater than, equal to, or 
less than string_2. 
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strncmp ( ) makes the same comparison but examines at most n characters. 

strcmp ( ) uses native character comparison, which is signed on Sun worksta- 
tions. 



strcpyO and strncpyO 

— Copy Strings 



r 


\ 


char *strcpy (string_l, string__2) 




char *string_l, *string_2; 




< 


.j 



— 

char *strncpy (string_l, string_2, n) 
char *string_l, *string_2; 

/ 



strcpy ( ) copies string string_2 to string_l, stopping after the null character 
has been moved, st r ncpy ( ) copies exactly n characters, truncating or null- 
padding string _2; the target may not be null-terminated if the length of string _2 
is n or more. Both return string _1 . 



strcat()and strncat() 

— Concatenate Strings 



r 


\ 


char *strcat (string__l, string_2) 




char * string_l, *string__2; 




s 


> 





\ 


char *strncat (string_l, string_2, n) 




char *string_l, *string_2; 




^ 


/ 



strcat ( ) appends a copy of string string_2 to the end of string string_l. 

strncat ( ) appends n characters at most. Both return a pointer to the null- 
terminated result. 

index () and rindex ( ) — index () returns a pointer to the first occurrence of character c in string s, or 
Find Character in String zero if c does not occur in the string. 

rindex ( ) returns a pointer to the last occurrence of character c in string s, or 
zero if c does not occur in the string. 



s 


\ 


char *index(s, c) 




char *s r c; 




v 


/ 





\ 


char *rindex(s f c) 




char c; 




\ — 


j 
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8.4. Byte String and Bit 
String Functions 



Functions described in this section operate on byte strings and bit strings. They 
do not recognize null-terminated strings, unlike the functions described in Sec- 
tion 8.3. 



bcmp ( ) — Compare Byte 
Strings 



bcopy ( ) — Copy Byte 
Strings 



/ 




bcmp(bl, b2, length) 




char *bl, *b2 ; 




int length; 




V . - _ - 






bcmp ( ) compares length bytes at address bl against length bytes at address b2, 
returning zero if they are identical, nonzero otherwise. 



r 


— 


bcopy (bl, b2, length) 




char *bl, *b2; 




int length; 




V 


J 



bcopy ( ) copies length bytes, in left-to-right order, from string bl to string b2. 

Overlapping strings are handled correctly. 

Note: The order of arguments is backwards from that of st rcpy ( ) — that 

is, bcopy ( ) copies from its first argument to its second argument, 
while st rcpy ( ) copies from its second argument to its first argu- 
ment. 



bzero ( ) — Clear Byte 
String to Zero 



r 


\ 


bzero (b, length) 




char *b; 




int length; 






J 



bz er o ( ) zeroes length bytes in the string b. 



f f s ( ) — Find First Bit Set 



r 


A 


ffs (i) 




int i ; 




V 


J 



f f s ( ) finds the first bit set in the argument passed it and returns the index of 
that bit. Bits are numbered starting at 1 from the right. A return value of -1 
indicates the value passed is zero. 
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Low-Level File I/O 



This appendix describes the bottom level of I/O on the SunOS system. The 
lowest level of I/O in SunOS provides no buffering or any other services except 
moving data; it is, in fact, a direct entry into the operating system. You are 
entirely on your own, but on the other hand, you have the most control over what 
happens. And since the calls and usage are quite simple, this isn’t as bad as it 
sounds. 

A.l. File Descriptors In SunOS, all I/O is done by reading or writing files, because all peripheral dev- 

ices, even the user’s terminal, are files in the file system. This means that a sin- 
gle, homogeneous interface handles all communication between a program and 
peripheral devices. 

In the most general case, before reading or writing a file, it is necessary to inform 
the system of your intent to do so, a process called ‘opening’ the file. If you are 
going to write on a file, it may also be necessary to create it. The system checks 
your right to do so: does the file exist? Do you have permission to access it? If 
all is well, the system returns a small positive integer called a file descriptor. 
From then on, whenever I/O is to be done on the file, the file descriptor is used 
instead of the name to identify the file. This is roughly analogous to the use of 
READ (5 , . . . ) and WRITE ( 6 , . . . ) in FORTRAN. All information about an 
open file is maintained by the system; the user program refers to the file only by 
the file descriptor. 

File pointers are similar in spirit to file descriptors, but file descriptors are more 
fundamental. A file pointer is a pointer to a structure that contains, among other 
things, the file descriptor for the file in question. 

Since input and output involving the user’s terminal are so common, special 
arrangements exist to make this convenient. When the command interpreter (the 
‘shell’) runs a program, it opens three files, with file descriptors 0, 1, and 2, 
called standard input, standard output, and standard error output. All of these are 
normally connected to the terminal, so if a program reads file descriptor 0 and 
writes to file descriptors 1 and 2, it can do terminal I/O without opening the files. 

If I/O is redirected to and from files with < and >, as in 
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the shell changes the default assignments for file descriptors 0 and 1 from the ter- 
minal to the named files. Similar observations hold if die input or output is asso- 
ciated with a pipe. Normally file descriptor 2 remains attached to the terminal, 
so error messages can go there. In all cases, the file assignments are changed by 
the shell, not by the program. The program does not need to know where its 
input comes from nor where its output goes, so long as it uses file 0 for input and 
1 and 2 for output. 

A.2. read ( ) and All input and output is done by two functions called read () and write (). 

wr i t e ( ) The first argument for both of these functions is a file descriptor. The second 

argument is a buffer in your program where the data is to come from or go to. 

The third argument is the number of bytes to be transferred. The calls are 



c 




a 




n__read = read(fd, buf, n) ; 






n__written = write (fd, buf, n) ; 




^ 







Each call returns a byte count which is the number of bytes actually transferred. 
On reading, the number of bytes returned may be less than the number asked for, 
because fewer than n bytes remained to be read in the buffer. When the file is a 
terminal, read ( ) normally reads only up to the next newline, which is generally 
less than what was requested. A return value of zero bytes implies end of file, 
and -1 indicates an error of some sort. For writing, the returned value is the 
number of bytes actually written; it is generally an error if this isn’t equal to the 
number supposed to be written. 

The number of bytes to be read or written is quite arbitrary. The two most com- 
mon values are 1, which means one character at a time (‘unbuffered’), and 1024, 
corresponding to the physical blocksize on many peripheral devices. This latter 
size will be most efficient, but even character-at-a-time I/O is not inordinately 
expensive. 

Note The file stdio defines the constant BUF512, but in the following small exam- 
ples, it is more efficient to have the definition in place. 

Putting these facts together, we can write a simple program to copy its input to 
its output. This program will copy anything to anything, since the input and out- 
put can be redirected to any file or device. 
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# define BUFSIZ 1024 

roain() /* copy input to output */ 

{ 

char buf [BUFSIZ]; 
int n ; 

while ( (n = read(0, buf, BUFSIZ)) > 0) 
write (1, buf, n) ; 
exit ( 0 ) ; 

1 

v / 

If the file size is not a multiple of BUFSIZ, some read ( ) will return a smaller 
number of bytes, and the next call to read ( ) after that will return zero. 

It is instructive to see how read ( ) and write ( ) can be used to construct 
higher-level routines like get char ( ) , put char ( ) , etc. For example, here is 
a version of getchar ( ) which does unbuffered input 




c must be declared char, because read ( ) requires a character pointer. The 
character being returned must be masked with Oxf f to ensure that it is positive; 
otherwise sign extension may make it negative. The constant Oxf f is appropri- 
ate for Sun workstations but not necessarily for other machines. 

The second version of get char ( ) does input in big chunks, and hands out the 
characters one at a time: 
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♦define CMASK Oxff /* for making char's > 0 */ 
♦define BUFSIZ 1024 
♦define EOF (-1) 

get char O /* buffered version */ 

{ 

static char buf [BUFSIZ]; 
static char *bufp = buf; 
static int n = 0; 

if (n 4 - 0) { /* buffer is empty */ 

n = read{G, buf, BUFSIZ); 
bufp = buf; 

1 |§ 111 

return (( — n >- 0) ? *bufp++ & CMASK : EOF ) ; 

} 



A.3. open ( ) , close ( ) , Other than the default standard input, output and error files, you must explicitly 

uni ink ( ) open files in order to read or write them. 

open ( ) is rather like the f open ( ) discussed in the previous section, except 
that instead of returning a file pointer, it returns a file descriptor, which is just an 
int. 



/ 




int fd; 




fd = open (name, rwmode); 




v 


/ 



As with f open ( ) , the name argument is a character string corresponding to the 
external file name. The access mode argument is different, however: rwmode is 
0 for read, 1 for write, and 2 for read and write access, open ( ) returns -1 if an 
error occurs; otherwise it returns a valid file descriptor. 

It is an error to try to open ( ) a file that does not exist. 

In the SunOS file system, there are nine bits of protection information associated 
with a file, controlling read, write and execute permission for the owner of the 
file, for the owner’s group, and for all others. Thus a three-digit octal number is 
most convenient for specifying the permissions. For example, 0755 specifies 
read, write and execute permission for the owner, and read and execute permis- 
sion for the group and everyone else. For more information about permissions, 
read the manual page for chmod(l). 

To illustrate, here is a simplified version of the SunOS utility cp, a program 
which copies one file to another. The main simplification is that our version 
copies only one file, and does not permit the second argument to be a directory: 
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♦define NULL 0 
♦define BUFSIZ 1024 

♦define PMODE 0644 /* RW for owner, R for group & others */ 

error (si, s2) /* print error message and die */ 

char *sl, *s2; 

{ 

print f (si, $2) ; 
printf ("\n") ; 
exit (1) ; 

main(argc, argv) /* cp: copy fl to f2 */ 
int argc; 
char *argv( ] ; 

iBiv- ; v .. y'-f’:’:.:, ~ ; 

int f 1, f2, n; 

Char buf [BUFSIZ] ; 

if (argc ! = 3) 

error ("Usage : cp from to", NULL); 
if ( (f 1 = open (argv [1 ] , 0)) == — 1) 

error ("cp: can't open %s", argv[l]); 

.5; iii:- ( = . treat (argv [ 23 PMODE ) ) =^= : 1) : : ' 
error("cp: can't create %s”, argv[2]); 

while {(n | read(fl, buf, BUFSIZ)) > 0) 
if (write (f 2 , buf, n) 1= n) 

error("cp: write error"/ NULL) ; 

exit (0) ; 



There is a limit (typically 64) on the number of files which a program may have 
open simultaneously. Accordingly, any program which intends to process many 
files must be prepared to reuse file descriptors. The routine close ( f d) breaks 
the connection between a file descriptor and an open file, and frees the file 
descriptor for use with some other file. File descriptors 0, 1, and 2 can also be 
closed if you need to obtain extra file descriptors. Program termination through 
exit or return from the main program closes all open files. 

The function unlink (filename ) removes the file filename from the file 
system. 

A.4. Random Access — File I/O is normally sequential: each read () or write () takes place at a 

lseek ( ) position in the file right after the previous one. When necessary, however, the 

data in a file can be read or written in any arbitrary order. The system call 
lseek ( ) provides a way to move around in a file without actually reading or 
writing: 
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N 


lseek (fd f offset, origin); 
v 


-J 



forces the current position in the file whose descriptor is f d to move to position 
offset, which is taken relative to the location specified by origin. Subse- 
quent reading or writing will begin at that position, offset is a long; f d and 
origin are int’s. origin can be 0, 1, or 2 to specify that offset is to be 
measured from the beginning, from the current position, or from the end of the 
file, respectively. For example, to append to a file, seek to the end before writ- 
ing: 



. 

lseek(fd, 0L, 2); 

* 



Note that in this case, if offset were nonzero, the length of the file would be 
extended by offset. 

To get back to the beginning (‘rewind’), 
— 
lseek (fd, 0L, 0) ; 



Notice the 0L argument; it could also be written as ( long) 0. 

With lseek ( ) , it is possible to treat files more or less like large arrays, at the 
price of slower access. For example, the following simple function reads any 
number of bytes from any arbitrary place in a file. 



get (fd, pbs> ^buf , in) /% read n bytes from position pos */ 
int fd, n; 
long pos; 
char *buf; 

{ 

lseek (fd, pos, 0); /* get to pos */ 

return (read (fd, buf, n) ) ; 

> 



A.5. Error Processing The routines discussed in this section, and in fact all the routines which are direct 

entries into the system, can incur errors. Usually they indicate an error by return- 
ing a value of -1. Sometimes it is nice to know what sort of error occurred; for 
this purpose all these routines, when appropriate, leave an error number in the 
external variable errno. The meanings of the various error numbers are listed 
in intro (2) in the Sun System Interface Manual so your program can, for exam- 
ple, determine if an attempt to open a file failed because it did not exist or 
because the user lacked permission to read it. Perhaps more commonly, you may 
want to display the reason for failure. The routine perror displays a message 
associated with the value of errno; more generally, sys_errno is an array of 




sun 

microsystems 



Revision A of 27 March, 1990 









Appendix A — Low-Level File I/O 69 



character strings which can be indexed by errno and displayed by your pro- 
gram. 
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fread ( ) 

File 



fwrite () 

File 




Binary I/O 



The binary I/O facilities of the C library provide for record-oriented sequential 
access to files. 

WARNING Using these routines may result in data incompatabilities when porting pro- 
grams to or from some other machines. See the description of Sun’s External 
Data Representation (XDR) standard for creating portable code as described in 
Network Programming 

Read Data from The fread () function reads some number of objects into a block, from a 
specified file. The interface to fread () is: 



fread (pointer, sizeof *pointer, items, stream) 
char *pointer; 
int items ; 

FILE *stream; 

^ j 

The arguments to fread ( ) have the following meanings: 
pointer is a pointer to a block of objects 

items is a count of the number of objects of a data type determined by the 
type of whatever pointer points to 

stream is the named input stream 

The value of the fread () function is the number of objects actually read. 

-Write Data to The fwrite () function writes some number of objects from a block, onto a 
specified file. The interface to fwrite () is: 



— 

fwrite (pointer, sizeof *pointer, items, stream) 
char *pointer; 
int items ; 

FILE *stream; 

v / 
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The arguments to fwriteO have the following meanings: 
pointer is a pointer to a block of objects 

items is a count of the number of objects of a data type determined by the 
type of whatever pointer points to 

stream is the named output stream 

The value of the f write ( ) function is the number of objects actually written 
to the named stream. 
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Memory Management 



These routines provide a general-purpose memory allocation package. They 
maintain a table of free blocks for efficient allocation and coalescing of free 
storage. When there is no suitable space already free, the allocation routines call 
sbrk (see brk(2)) to get more memory from the system. 

Each of the allocation routines returns a pointer to space suitably aligned for 
storage of any type of object. They return a null pointer if the request cannot be 
completed. 



C.l. malloc ( ) — 

Allocate Memory 



C.2. free () — Free 
Allocated Memory 



r 


N 


char *malloc (num) 




unsigned num; 




\ 


. _ j 



allocates num bytes. The pointer returned is aligned so as to be usable for any 
purpose. NULL is returned if no space is available. The result of malloc (0 ) is 
undefined. 



r 


a 


int free(ptr) 




char *ptr; 






j 



freed frees up memory previously allocated by malloc () . Disorder can be 
expected if the pointer was not obtained from malloc ( ) . 



C.3. calloc ( ) — 

Allocate Memory for 
C Objects 



( 


\ 


char *calloc(num, size); 




unsigned num.- 




unsigned size; 






j 



allocates space for num items, each of size size. The space is guaranteed to be 
set to 0 and the pointer is aligned so as to be usable for any purpose. NULL is 
returned if no space is available. 
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C.4. cfreeO — Free 
Allocated Memory 



r 


A 


(void) cfree(ptr, num, size) 




char *ptr; 




unsigned num; 




unsigned size; 




V 





Space is returned to the pool used by calloc ( ) . Disorder can be expected if 
the pointer was not obtained from calloc ( ) . 



C.5. realloc () — 

Change Size of 
Allocated Block 



realloc ( ) changes the size of the block referenced by ptr to size bytes and 
returns a pointer to the (possibly moved) block. The contents will be unchanged 
up to the lesser of the new and old sizes. For backwards compatibility, real- 
loc ( ) accepts a pointer to a block freed since the most recent call to mal- 
loc ( ) , calloc ( ) , realloc ( ) , valloc ( ) , or memalign ( ) . Note that 
using realloc ( ) with a block freed before the most recent call to malloc ( ) , 
calloc () , realloc ( ), valloc ( ) , or memalign () is an error. 



r 


a 


char *realloc (ptr f size) 




char *ptr; 




unsigned size; 




l ... 


j 



C.6. memalign () — 

Allocate to Alignment 
Boundary 



memalign ( ) allocates size bytes on a specified alignment boundary, and 
returns a pointer to the allocated block. The value of the returned address is 
guaranteed to be an even multiple of alignment bytes. Note that the value of 
alignment must be a power of two, and must be greater than or equal to the size 
of a word. 



— 

char *memalign (alignment, size) 
unsigned alignment; 
unsigned size; 

\ ^ 



realloc ( ) , valloc ( ) , and memalign ( ) return NULL and set errno if 
arguments are invalid, or if there is insufficient available memory, or if the heap 
has been delectably corrupted, for example, by storing outside the bounds of a 
block. 



C.7. valloc ( ) — 

Allocate Memory on a 
Page Boundary 



valloc (size) is equivalent to memalign ( get page size () , size). 



r " ~ 


\ 


char *valloc (size) 




unsigned size; 




V 


J 
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C.8. allocaO — 

Allocate Memory on 
Stack 



alloca ( ) allocates size bytes of space in the stack frame of the caller, and 
returns a pointer to the allocated block. This temporary space is automatically 
freed when the caller returns. 



r 




char *alloca (size) 




int size; 




v 


j 



Warning allocaO is both machine- and compiler-dependent; its use is strongly 

discouraged. It is possible to request more stack space than is available, but if 
you do, there is no way to detect this condition. 



C.9. Memory Allocation More detailed diagnostics can be made available to programs using the memory 

Debugging management routines described in this chapter by including a special relocatable 

object file at link time. This file also provides routines for control of error han- 
dling and diagnosis, as defined below. Note that these routines are not defined in 
the standard library. 



malloc_debug ( ) — Set 

Debug Level 



f 


■N 


int malloc_debug (level) 




int level; 






-J 



malloc_debug ( ) sets the level of error diagnosis and reporting during subse- 
quent calls to malloc ( ) , calloc ( ) , realloc ( ) , valloc ( ) , 
memalign ( ) , cf ree ( ) , and free ( ) . The value of level is interpreted as 
follows: 

0 malloc ( ) , calloc ( ) , realloc ( ) , valloc ( ) , memalign ( ) , 
cf ree ( ) , and free ( ) behave the same as in the standard library. 

1 malloc ( ) , calloc ( ) , realloc ( ) , valloc ( ) , memalign ( ) , 
cf ree ( ) , and free ( ) abort with a message to stderr if errors are 
detected in arguments or in the heap. If a bad block is encountered, 
its address and size are included in the message. 

2 Same as level 1, except that the entire heap is examined on every call 
to malloc ( ) , calloc ( ) , realloc ( ) , valloc ( ) , 
memalign ( ) , cf ree ( ) , and free ( ) . 

malloc_debug ( ) returns the previous error diagnostic level. The default 
level is 1. 



malloc_verify ( ) — 

Check Storage Allocation 
Heap 



/ 

int malloc__verify ( ) 

v, > 



malloc_ver if y ( ) attempts to determine if the heap has been corrupted. It 
scans all blocks in the heap (both free and allocated) looking for strange 
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addresses or absurd sizes, and also checks for inconsistencies in the free space 
table. malloc_verify ( ) returns 1 if all checks pass without error, and other- 
wise returns 0. The checks can take a significant amount of time, so it should not 
be used indiscriminately. 

The file / usr/lib/debug/malloc . o contains the diagnostic versions of 
malloc ( ) , free ( ) , etc. 

malloc ( ) , calloc ( ) , realloc ( ) , valloc ( ) , memalign ( ) , 
cf ree ( ) , and free ( ) set errno as follows: 

EINVAL an invalid argument was given. The value of ptr given to f ree ( ) , 
cf ree ( ) , or realloc ( ) must be a pointer to a block previously 
allocated by malloc ( ) , calloc () , realloc ( ) , valloc ( ) , 
or memalign ( ) . EINVAL is also true if the heap is found to have 
been corrupted. More detailed information may be obtained by ena- 
bling range checks using malloc_debug ( ) . 

ENOMEM size bytes of memory could not be allocated. 



C.10. Errors from Memory 
Management 
Routines 
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Sun C Data Representations 



This appendix describes how Sun C represents data in storage and the mechan- 
isms for passing arguments to functions. This chapter is intended as a guide to 
programmers who wish to write or use modules in languages other than C and 
have those modules interface to C code. 

D.l. Storage Allocation This section describes how storage is allocated to variables of various types. 

In general, any word value is always aligned on a two-byte boundary. Values 
that can fit into a single byte are aligned on a byte boundary. 



T able D- 1 Storage Allocation for Data Types 



Data Type 


Internal Representation 


char elements 


a single 8-bit byte. 


short integers 


one word (two bytes or 16 bits), aligned on a two-byte boun- 
dary. 


int and long 


32 bits (four bytes or two words), aligned on a two-byte boun- 
dary. 


float 


32 bits (four bytes or two words), aligned on a two-byte boun- 
dary. A float has a sign bit, 8-bit exponent and 23-bit frac- 
tion. On a Sun-4, they are aligned on 4-byte boundaries. 


double 


64 bits (eight bytes or four words), aligned on a word boundary. 
A double element has a sign bit, an 1 1-bit exponent and a 
52-bit fraction. On a Sun-4, they are aligned on 8-byte boun- 
daries. 



D.2. Data Representations Bit numberings of any given data element depend on the architecture in use: 

Sun- 3s, Sun-4s, and SPARCStations use bit 0 as the most significant bit, with 
byte 0 being the most significant byte. 
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Integer Representations There are three integer types used in Sun C: short, int, and long . 

Table D-2 Representation of short 



Bits 


Content 


8-15 


ByteO 


0-7 


Byte 1 



Table D-3 Representation of int and long 



Bits 


Content 


24-31 


ByteO 


16-23 


Byte 1 


8-15 


Byte 2 


0-7 


Byte 3 



float and double float and double data elements are represented according to the ANSI IEEE 

Representation 754-1985 standard. The tables below, 

5 = sign (1 bit) 

e = biased exponent ( 1 lbits) 

/ = fraction (23 bits) 

u - unsigned 



Table D-4 float Representation 



Bits 


Name 


Content 


31 


Sign 


1 iff number is negative. 


23-30 


Exponent 


Eight-bit exponent, biased by 127. Values of all zeros, and all 
ones, reserved. 


0-22 


Fraction 


23-bit fraction component of normalized significand. The "one" 
bit is "hidden". 
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Table D-5 double Representation 



Bits 


Name 


Content 


63 


Sign 


1 iff number is negative. 


52-62 


Exponent 


Eleven-bit exponent, biased by 1023. Values of all zeros, and all 
ones, reserved. 


0-51 


Fraction 


52-bit fraction component of normalized significand. The "one" 
bit is "hidden". 



A float or double number is represented by the form: 



^(exponent —bias ) ^ y 



Extreme Number 
Representation 



where “l.f” is the significant! and “f” is the bits in the significand fraction. 

Normalized float and double numbers are said to contain a "hidden" bit, 
providing for one more bit of precision than would otherwise be the case. 



Table D-6 float Representations 



normalized number (0<e<255): 


^exponent— 127) j y 


subnormal number (e=0, f!=0): 


2< 126 ) 1 f 


zero (e=0, f=0): 


(-l) Sign 0 


signaling NaN 
Quiet NaN 
Infinity 


s=u, e=255(max); f=.0uuu-uu (at least one bit must be nonzero) 

s=u, e=255(max); f=.luuu-uu 

s=u, e=255(max); f=.0000-00 (all zeroes) 



Table D-7 double Representations 



normalized number (0<e<2047): 


2( ex P onent -l023) J y 


subnormal number (e=0, f ! =0) : 


2 (1022) l.f 


zero (e=0, f=0): 


(-1 ) Sign 0 


signaling NaN 
Quiet NaN 
Infinity 


s=u, e=2047(max); f=.0uuu-uu (at least one bit must be nonzero) 

s=u, e=2047(max); f=.luuu-uu 

s=u, e=2047(max); f=.0000-00 (all zeroes) 
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Hexadecimal Representation 
of Selected Numbers 



Value 


float 


double 


+0 


00000000 


0000000000000000 


-0 


80000000 


8000000000000000 


+1 . o 


3F800000 


3FF 0000000000000 


-1.0 


BF800000 


BFF0 00 00 00 00 0000 


+2.0 


40000000 


4000000000000000 


+3.0 


40400000 


4008000000000000 


+Inf inity 


7F800000 


7FF0 00 00 00 0000 00 


-Infinity 


FF800000 


FFF0 00 00 00 00 00 00 


NaN 


7F8xxxxx 


7FFxxxxxxxxxxxxx 



Pointer Representation 
Array Storage 



Arithmetic Operations on 
Extreme Values 



A pointer in C occupies four bytes. The NULL value pointer is equal to zero. 

Arrays are stored with their elements in a specific storage order. The elements 
are actually stored in a linear sequence of storage elements. 

C arrays are stored in row-major order; the last subscript in a multi-dimensional 
array varies fastest. 

String data types are simply arrays of char elements. 

This subsection describes the results derived from applying the basic arithmetic 
operations to combinations of extreme and ordinary floating-point values. 

No traps or any other exception actions are taken. 

All inputs are assumed to be positive. Overflow, underflow, and cancellation are 
assumed not to happen. In all the tables below, the abbreviations have the fol- 
lowing meanings: 



Table D-8 Extreme Values Usage 



Abbreviation 


Meaning 


Num 


Subnormal or Normalized Number 


Inf 


Infinity (positive or negative) 


NaN 


Not a Number 


Uno 


Unordered 



The tables that follow describe the types of values that result from arithmetic 
operations performed with combinations of different types of operands. 
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Table D-9 Addition and Subtraction Results 



Addition and Subtraction 



Left Operand 




Right Operand 






0 


Num 


Inf 


NaN 


0 


0 


Num 


Inf 


NaN 


Num 


Num 


Num 


Inf 


NaN 


Inf 


Inf 


Inf 


Note 


NaN 


NaN 


NaN 


NaN 


NaN 


NaN 



Note: Inf + Inf = Inf; Inf-Inf = NaN 



Table D-10 



Table D- 11 



Multiplication Results 





Multiplication 






Left Operand 




Right Operand 






0 


Num 


Inf 


NaN 


0 


0 


0 


NaN 


NaN 


Num 


0 


Num 


Inf 


NaN 


Inf 


NaN 


Inf 


Inf 


NaN 


NaN 


NaN 


NaN 


NaN 


NaN 



Division Results 



Division 


Left Operand 




Right Operand 






0 


Num 


Inf 


NaN 


0 


NaN 


0 


0 


NaN 


Num 


Inf 


Num 


0 


NaN 


Inf 


Inf 


Inf 


NaN 


NaN 


NaN 


NaN 


NaN 


NaN 


NaN 
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T able D- 1 2 Comparison Results 



Comparison 


Left Operand 




Right Operand 






0 


Num 


Inf 


NaN 


0 


= 


< 


< 


Uno 


Num 


> 




< 


Uno 


Inf 


> 


> 




Uno 


NaN 


Uno 


Uno 


Uno 


Uno 



Note: NaN compared with NaN is Unordered, and also results in inequality. 

+0 compares equal to -0. 



D.3. Argument Passing 
Mechanism 



This section describes how arguments are passed in Sun C. 

All arguments to C functions are passed by value. 

Actual arguments are pushed onto the stack in the reverse order from which they 
are declared in a function declaration. 



Actual arguments which are expressions are evaluated before the function refer- 
ence. The result of the expression is then pushed onto the stack. 

Sun-3 On Sun-3s, functions return their results in register DO, or in registers DO and D1 
when the result is a double value. 

Sun-4 On Sun-4s, functions return integer and float results in register %o0, while 
double results are returned in %of 0 and %of 1. 



All arguments, except doubles, are passed as four-byte values; a double is 
passed as an eight-byte value. All float values are passed as doubles. 

Upon return from a function, it is the responsibility of the caller to pop argu- 
ments from the stack. 



D.4. Referencing Data 
Objects in C 



This section describes how variables of different types are actually accessed (or 
referenced). The method and notations of access, of course, differ depending on 
whether the object is a simple variable, an array, a structure, or a union. 



Referencing Simple Variables A plain variable (of simple scalar type) is accessed by its identifier. Since such a 

simple variable has no structure, its identifier alone is enough to reference it. 
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Figure D-l Examples of Simple Variable References 




Referencing With Pointers A variable can also be declared as a pointer to another object. In this case, the 

reference to the object must be done with the pointer notation. Placing an aster- 
isk character * in front of an identifier uses that identifier as a pointer to an 
object, and the thing that is read from or written to is the object that the identifier 
points to. 

Figure D-2 Examples of Pointer References 



f 




/* 


"N 

Declare some pointer variables */ 


int *egress; 








float ^lightly; 






char *coal; 








extern double 


sin () ; 








/* 


Now reference those variables */ 


*egress = 10; 




/* 


Set it to a constant */ 


printf (”%f ", 


sin 


<* 


lightly) ) ; /* Pass it as argument */ 


putc (*coal) ; 

v 




/* 


Write it to the standard output */ 

... . j 



Referencing Array Elements When an identifier of an array type appears in an expression, the identifier is con- 
verted to a pointer to the first member of the array. 

The subscript operation [ ] is interpreted such that 
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is equivalent to the construct 



*((E1) + (E2)) 



Figure D-3 Examples of Array Variable References 

< > 
/* Declare some array variables */ 

int egress [10]; 
float lightly [5] [5] ; 
char coal[100]; 
extern double sin(); 
int idx; 
int idy; 

/* Now reference those variables */ 
for (idx = 0; idx < 10; idx++) 

egress [idx] =10; /* Set int to a constant */ 

for (idx = 0; idx <5; idx++) 

for (idy =0; idy <5; idy++) 

printf ("%f", sin (lightly [idx] [idy] ) ) ; 

for (idx = 0; idx < 100; idx++) 

putc (coal [idx]); /* Write to standard output */ 

v ) 



Referencing Structures and There are only three operations which may be done on a structure or a union: 

n '° nS 1 . A member of the structure or union can be referenced by means of the 

. or -> operator. 

2. The address of the entire structure or union can be taken, with the & 
operator. 

3. One structure can be copied to another of the same type with the 
assignment operator. 

The . operator is used in contexts where the structure or union identifier is avail- 
able directly to the expression. The -> operator is used when the identifier for 
the structure or union is a pointer to the object. Structures can also be passed as 
parameters, returned from functions, or assigned to variables of the same struc- 
ture or union type. 
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Figure D-4 Examples of Accessing Members of Structures 



— 

#def ine MAXLEN 256 
#def ine NULL 0 

demo (wanted) 

char ^wanted; 

r 


> 


\ 

/* Declare a couple of 
struct { /* This one is fairly simple 

int level; 
char *cp; 

char pbuf fer [MAXLEN] ; 

} putter; 


structures */ 
*/ 


struct vallist { /* This one is a linked 

char *name; 
char valtype; 
int value; 

struct vallist *nextval; 

} *valhead, *valtail; 


list */ 


struct vallist ^pointer; 

/* Now access the members 
putter. level = 10; 
for ( i — 0 ; i < MAXLEN; i++) 

putter .pbuf fer [i] = sputter. cp; 


*/ 


/* Access members through pointers */ 
for (pointer = valhead; 

pointer != NULL; 

pointer = pointer->nextval) 
if (strcmp (pointer->name, wanted) = : = 0) 
return (pointer) ; 


} /* End of the demo function */ 


j 
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Sun C Extensions 



The language described by Kemighan and Ritchie in The C Programming 
Language (referred to hereafter as “K&R C”), while close to Sun C, is not identi- 
cal to it. The extensions to K&R C embodied in Sun C are described below, with 
the relevant section of Appendix A of The C Programming Language listed for 
each topic discussed. 



E.l. Keywords (§A.2.3) 



E.2. Name Spaces (§A.4) 



E.3. Characters and 
Integers (§A.6.1) 



Sun C includes the additional keywords void and enum. 

In Sun C, functions may be declared to return the type void. This means that 
the function doesn’t return any value, and so is functionally a subroutine. There 
are no objects of type void. 

Sun C provides separate address spaces for 

□ struct/union and enum tags 

□ Elements of each different type of struct/union 

□ Everything else: regular variables and functions 

K&R C provides two name spaces: one for struct/union tags, and the other 
for all variables, functions, typedef ’d names, and so on. 

Sun C’s characters are signed, and all ASCII characters are positive. Unsigned 
characters are, of course, unsigned, and promote to unsigned. See also refer- 
ence to 8.2 below. 



E.4. float and double InK&RC, whenever a float appears in an expression it is lengthened to dou- 
(§A.6.2) ble by zero- padding its fraction. 

In Sun C, floats are lengthened to doubles in expressions, but with consider- 
ably more work, since the exponent part is of a different width, and of a different 
bias. (See Chapter D for further discussion.) 

Sun C also provides a compiler option, -f single, to avoid this widening in 
expressions using only floats, -f single will not prevent float formal 
parameters from being rewritten as doubles, nor float-valued actual parame- 
ters from being promoted to double. 
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E.5. Arithmetic 

Conversions (§A.6.6) 



Unsigned char and unsigned short promote to unsigned. Since in SunC 
long == int, nothing ever promotes to long. 



E.6. Primary Expressions 
(§A.7.1) 



Sun C supports passing structs and unions by value. The C Programming 
Language does not discuss the possibility of passing structs or unions as 
value parameters since it is not allowed in K&R C. See §A.10.1 below. 



E.7. Multiplicative The C Programming Language states that % may not be applied to operands of 

Operators (§A.7.3) type float. In Sun C, it may not be applied to operands of type double, 

either. Note that the sign of the remainder is the same as the sign of the divi- 
dend. 



E.8. Storage Class In Sun C, any integral type (combinations of char, short, int, long, 

Specifiers (§A.8.1) unsigned, and enum) and any pointer type may be assigned to registers. 

Depending on the hardware present, floats and doubles may be, too. 

In K&R C, only int, char, and pointer types may be assigned to registers 
with the register storage class. 



E.9. Type Specifiers Sun C supports the scalar types char, unsigned char, int, short int, 

(§A.8.2) unsigned short int, long int, enum, float, and double. 

K&R C does not support the unsigned char, unsigned short int, or 
enum types. These types in Sun C promote to unsigned int rather than 
int. 



E.10. Declarator Naming 
(§A.8.4 and §A.14.1) 
E.ll. struct and union 
Declarations (§A.8.5 
and §A.14.1) 



Sun C permits declaring a function returning a struct or union. 



Sun C permits you to both assign structs/unions and pass them as parame- 
ters. 

In Sun C, fields are packed left-to-right within a storage unit appropriate to the 
type they are declared to be. They may be declared as any of the integer type, 
and enum. No matter what their declaration, all fields are unsigned, and thus 
zero-extended for the purposes of "the normal conversions". 

In Sun C, interpretation of . and -> take into account the type of the 
struct/union or pointer expression on the left to determine the name on the 
right. This permits apparent clashes between offsets and types between members 
of different aggregates having the same name. The only difficulty comes if the 
type of the left-hand expression does not properly disambiguate the name, in 
which case: 



1: If there is no ambiguity, then the only choice is taken and a warning is 

issued. 

2: If there is ambiguity, the program is considered to be in error. 
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E.12. Switch Statement 
(§A.9.7) 



Sun C accepts switch expression of types float, double (fixed to ints), and 
enum, as well as the integer types permitted by K&R C. 



E.13. External Function 
Definitions (§A.10.1) 



Sun C permits passing struct and union value parameters in external func- 
tions. 



E.14. Lexical Scope 
(§A.11.1) 



E.15. Scope of Externals 
(§A.11.2) 



E.16. Explicit Pointer 
Conversions 
(§A.14.4) 



Sun C does not "push down" an outer variable declaration in a compound state- 
ment if a variable of class extern is re-declared in an inner block. In this case, 
the inner declaration persists until the end of the file, and if it redeclares a name 
with a definition in an outer block, it will elicit a complaint from the compiler 
about redeclaring a variable. 

Sun C’s linking rules are somewhat more liberal than those implied by K&R C: 

□ C uninitialized global data are treated like FORTRAN uninitialized 
COMMON (a tentative definition). Sun C initialized data are are 
treated like FORTRAN COMMON initialized by BLOCK DATA (a 
true definition). 

□ A tentative definition in a library module will not cause the module to 
be loaded. A true definition will, if the the name occurs as a reference 
or tentative declaration in a module that is already being linked. (The 
"already" here is important since order matters.) 

□ If the linker sees any true definitions of a name among the modules to 
be linked, this definition overrides all tentative definitions. This 
includes the case where the true definition allocates less space for the 
named object than the tentative definition(s) would. 

□ If the linker sees no true definitions of a name, the name is defined by 
the linker, and space is allocated. The amount of space allocated 
should be the maximum of the size specified in any of the tentative 
definitions in the modules being linked. 

On Sun workstations, a pointer corresponds to a 32-bit integer, while addresses 
are measured in 8-bit bytes. Alignment of data depends on the particular plat- 
form. 

For more about data representation, see Chapter D . 



E.17. Constant Expressions Sun C permits cast operators as part of constant expressions, except in preproces- 

(§ A.15) sor constant expressions (see § 1 2.3), where the s i z eo f operator is also disal- 

lowed. 



E.18. Anachronisms Sun C does not recognize any of the anachronisms listed in § A. 17 of The C Pro- 

(§A.17) gramming Language. 
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